Agents
Define your own specialist subagents as markdown files. Empryo also reads the agent folders you already have for Claude Code, opencode and Gemini CLI.
Copy & share
On this page8 sections
A custom agent is a markdown file that describes a specialist: what it's for, which model runs it, which tools it may use, and the instructions it follows. When Empryo splits work across parallel helpers, it can hand a task to your specialist instead of a general-purpose one.
Use one when you keep giving the same kind of instructions: "review this for security issues", "find the slow paths, don't edit anything", "write release notes in our style".
Empryo uses the same file layout as Claude Code, opencode and Gemini CLI, and reads their folders. An existing .claude/agents/reviewer.md works with no changes.
Write oneLink to this section
Create a markdown file with name and description in the frontmatter. The body is the agent's instructions.
---
name: perf-hunter
description: Finds hot paths and allocation churn. Use before optimizing anything.
mode: explore
tools: read, grep, genome_analyze
effort: low
---
You hunt for performance problems. Report the top 3 hot paths with `file:line`
and the measured or inferred cost of each. Never edit files.Save it as .empryo/agents/perf-hunter.md in your project. Empryo picks up new and edited files within a few seconds. You don't need to restart.
Run /agents to see every definition Empryo found, grouped by project and global scope. In the terminal UI, press Enter on a row to read the full instructions, or r to re-scan. The desktop app shows the same list in a drawer.
Where Empryo looksLink to this section
Empryo scans these folders, including subfolders, so you can organize files like agents/review/security.md. An agent's identity is its name field, or the filename if name is missing. The folder path doesn't matter.
When two files use the same name, the one higher in this list wins. Project folders always beat global ones, and within each scope Empryo's own folder comes first.
.empryo/agents/ project
.agents/agents/ project
.opencode/agents/, .opencode/agent/ project (opencode)
.gemini/agents/ project (Gemini CLI)
.claude/agents/ project (Claude Code)
~/.empryo/agents/ global
~/.agents/agents/ global
~/.config/opencode/agents/, …/agent/ global (opencode)
~/.gemini/agents/ global (Gemini CLI)
~/.claude/agents/ global (Claude Code)FrontmatterLink to this section
Only name and description are required. Every other field limits or tunes the agent.
| Field | What it does |
|---|---|
name | Unique id, lowercase with hyphens. Defaults to the filename |
description | When to use this agent. Empryo reads this to decide when to delegate |
mode | explore (read-only) or code (may edit files). Leave it out to let the task decide |
model | A full provider/model id, or a short alias (see below) |
tools | Only these tools are allowed. Leave it out to allow the normal set |
additionalTools | Extra Empryo-only tools to allow on top of tools, so the file still works in other agents |
disallowedTools | Tools to remove, applied after tools |
effort | Reasoning effort for this agent |
maxTurns | Maximum number of steps the agent may take |
skills | Skills to load into the agent's context at start |
temperature | Sampling temperature for this agent |
color | Color used for the agent in panels and transcripts |
Empryo ignores keys it doesn't know. A permission: block written for another tool won't break the file.
Read-only or editingLink to this section
mode decides whether the agent can change files. If the file sets a mode, that mode always applies. An explore agent stays read-only even when it's given an editing task. opencode's subagent and primary values are understood too.
The tools list is enforced. If the agent tries a tool that isn't on the list, the call is refused with a message naming the agent that blocked it.
A custom agent can never get more power than the session allows. If your session is read-only, so is every agent it starts.
ModelsLink to this section
A full provider/model id is used exactly as written. Short aliases such as haiku, sonnet or fast map onto the fast model you've configured in Empryo, because the author's provider may not be yours. inherit, or no model field, uses whatever model Empryo would have picked.
Run oneLink to this section
Empryo chooses one of your agents on its own when a task matches its description. So write the description as a rule for when to use it ("Use after writing or modifying code"), not as a title.
You can also ask for one by name in your prompt ("have perf-hunter look at the boot path"). The agent can run it as a parallel helper within the current turn, or in the background while you keep working.
In a headless run, you can run the whole session as one of your agents:
empryo --headless --agent perf-hunter "why is the boot path slow?"If the name doesn't exist, Empryo stops with an error that lists the available agents. It won't quietly fall back to the default.
Helpers running as a custom agent show its name: in the desktop Subagents panel and in the terminal UI's dispatch tree.
ProfilesLink to this section
A custom agent can also run a whole tab, with its own model, mode, skills and routing. That's a profile: pick it with /profile <name> and turn it off with /profile off.
Let Empryo write oneLink to this section
Describe a role you want to reuse ("a release-notes writer that follows our CHANGELOG style") and ask Empryo to save it as an agent. It writes the file to .empryo/agents/, or to ~/.empryo/agents/ if you ask for a global one, and can use it in the same turn.
If another folder already has an agent with the same name, Empryo tells you which file wins, so a new definition never loses silently to an old .claude/agents/ copy.