How it works
A plain mental model of Empryo: the apps you use, the agent and its helpers, the tools it calls, the Genome map of your code, and memory across sessions.
Copy & share
On this page8 sections
Empryo is an AI coding agent. You describe a task, and it reads your code, edits files, runs your tests and reports back. This page explains the main parts so you know what is happening when it works.
Where you use itLink to this section
You can drive the same agent from three places. Pick whichever fits the job.
| App | Good for |
|---|---|
| Desktop app | Day-to-day work with panels for files, diffs, a browser and terminals |
| Terminal UI | Working inside a terminal, with an embedded Neovim editor (Ctrl+E) |
| Headless CLI | Scripts and CI: empryo --headless "your task" |
Your config, sessions and project settings are shared between them.
The agent and its helpersLink to this section
The agent you talk to is called Forge. It plans the work, calls tools and answers you. For bigger tasks it can hand pieces of work to helper agents that run in parallel and report back. The main agent uses the model you picked. It delegates research, edits and web searches automatically when useful. You can choose default models for those jobs in /router, without managing individual dispatches.
You can also define specialist agents with their own model, instructions and tool permissions, or connect them in workflows with parallel reviews, decisions and loops. Automatic research and editing roles are not a limit on the teams you can build.
When several helpers run at once, they share file reads so the same file is not loaded from disk repeatedly. Writes to the same file are queued rather than raced, and one helper's findings reach the others at their next step.
Web searchLink to this section
Some providers can run a web search on their own servers. When your model supports it, the model searches directly and no helper agent is needed. Otherwise Empryo's web search helper does the work. To keep every search on Empryo's side, set `nativeSearch` to false.
ToolsLink to this section
The agent works by calling tools: read a file, edit a file, run a shell command, search the code, run your tests. Many tools do a whole job in one call. For example, renaming a symbol updates every file that uses it. See compound tools and the tool reference.
The Genome: a map of your codeLink to this section
When you open a project, Empryo scans it and builds the Genome, a ranked map of your files, the symbols they export and how they depend on each other. A short version of that map goes into every prompt, so the agent already knows where things live before it starts searching. The map updates as files change. See the Genome.
Code intelligenceLink to this section
To find definitions, references and type errors, the agent uses the same language servers your editor uses. When no language server is available, it falls back to parsing the code directly. After each edit it checks for new errors, so it can fix its own mistakes early. See code intelligence.
MemoryLink to this section
Empryo can remember decisions and facts about your project between sessions, such as "we use pnpm here" or "this API is deprecated". See memory.
What goes into each promptLink to this section
Each turn, the agent sees your message plus some context: the current mode, basic project and git information, the Genome, relevant memories, your project instruction files such as EMPRYO.md, and any skills you loaded. Files you just edited or mentioned rank higher in the map for that turn.