Theora starter template

A working FERAL agent with one tool, in under ten minutes.

FERAL is Theora's runtime: a local-first AI agent that runs on your own machine, keeps its own memory, and talks to hardware. It is open source under Apache-2.0. Theora glasses are one device it drives. You do not need glasses to build for it.

Install

macOS 13+ or Linux (Ubuntu 22.04+, Fedora 40+, Arch). Python 3.11+.

./install.sh

Clones and installs FERAL, creates a virtualenv, and registers the example tool.

Run

./run.sh

Starts the brain and opens a prompt. Ask it something:

> save a note: waveguide supplier call moved to Thursday
> what notes do I have?

Both go through tools/notes.py, the example tool in this template. Nothing leaves your machine.

The example tool

tools/notes.py is about forty lines. It stores plain-text notes in ~/.theora-starter/notes.jsonl and exposes two actions to the agent.

A tool is a Python file that declares what it can do and what each action takes. FERAL reads that declaration and decides when to call it. To add your own, copy notes.py, change the name and the actions, and restart.

Where to go next

• GLANCE.md in the emulator folder: the three-line card format for the glasses display
• hud-emulator/: run the display on your laptop, no hardware needed
• The challenge: build one thing you would use every day on glasses with no keyboard and a three-line display

Troubleshooting

python3: command not found: install Python 3.11 or later.

FERAL starts but the tool is missing: the brain caches tools at startup. Stop it and run ./run.sh again.

Port already in use: another FERAL instance is running. Stop that one first.