Agent Types
Project Workers
One per registered project. Wraps
claude -p for full codebase access via Claude Code CLI.Standard Agents
Loaded from AGENT.md files. Get MCP tools + built-in tools. Best for focused tasks.
Deep Research Agents
Powered by
deepagents. Persistent workspaces, planning middleware, and summarization.How Routing Works
The supervisor reads the user’s message and decides which agent to delegate to based on:- Agent descriptions — each agent declares what it’s good at in its AGENT.md
- Conversation context — what’s been discussed so far
- Available tools — which agent has the right tools for the job
Agent Sources
Agents are loaded from two sources at startup:Project Agents
Configured viaAGENT_DIRS in .env:
*/AGENT.md files. These become standard agents with access to MCP tools and built-in tools.
Octo-Native Agents
Stored in.octo/agents/*/AGENT.md. These are managed by Octo itself — create them with the /create-agent wizard or manually.
Built-in Tools
Available to all agents (configurable per agent viatools: in AGENT.md):
| Tool | Description |
|---|---|
Read | Read file contents |
Grep | Search file contents with regex |
Glob | Find files by pattern |
Edit | Edit files with string replacement |
Bash | Execute shell commands |
claude_code | Delegate to Claude Code CLI (claude -p) |
Agent Lifecycle Tools
Every worker agent automatically receives two lifecycle tools (even if not listed in AGENT.md):| Tool | Description |
|---|---|
task_complete(summary) | Signal that work is done. The summary is the only thing the user sees — without this, the agent’s work is lost. |
escalate_question(question) | Ask the user a question when blocked. The question is relayed through the supervisor. |
These tools are injected into every agent’s system prompt automatically. Agents are instructed to always call
task_complete before finishing — never silently transfer back to the supervisor.Supervisor-Only Tools
The supervisor has additional tools not available to workers:| Tool | Description |
|---|---|
write_todos / read_todos | Task planning and progress tracking |
write_memory / update_long_term_memory | Persistent memory across sessions |
update_state | Update project STATE.md |
schedule_task | Schedule cron jobs |
dispatch_background | Spawn a background worker task |
send_file | Send files via Telegram |
Direct Agent Access
Skip the supervisor and send a prompt directly to a specific agent:/agents.