Odysseus Agent is a multi-round autonomous loop that can plan and execute complex tasks without you hand-holding every step. Built on the same foundation as opencode and the Model Context Protocol (MCP), Agent mode goes far beyond single-turn chat: it calls tools, reads results, adjusts its approach, and keeps iterating until the task is genuinely complete — or it tells you plainly why it can’t proceed.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/pewdiepie-archdaemon/odysseus/llms.txt
Use this file to discover all available pages before exploring further.
How the loop works
When you send a message in Agent mode, the loop runs like this:- LLM decides — The model reads the conversation history and your request. If it needs to take an action, it emits a fenced code block (or a native function call) specifying which tool to use and with what arguments.
- Tool executes — Odysseus intercepts the tool block, executes it (shell command, web search, file write, etc.), and captures the result.
- Result fed back — The tool output is appended to the message history and the model generates its next response.
- Repeat — The loop continues for up to 50 rounds (configurable) until the model signals it is done, hits the tool budget, or encounters an unrecoverable blocker.
Built-in tools
The following tools are available to the agent. Which tools appear in any given turn is determined by a RAG-based retrieval step that selects only the tools relevant to your request — keeping the context lean for smaller models. Several tools (shell, file access, memory, email, calendar) are restricted to admin users by default; see the Permissions section below.web_search — Search the web
web_search — Search the web
Runs a query against the configured SearXNG instance and returns ranked results. Used for current information, fact-checking, and research tasks. For multi-step research jobs, use the
trigger_research tool instead (which kicks off a Deep Research job).web_fetch — Fetch a URL
web_fetch — Fetch a URL
Fetches and reads the text content of a specific URL. Useful when the agent already has a URL and needs the full page content.
bash — Run shell commands
bash — Run shell commands
Executes shell commands with a 60-second timeout and a 10,000-character output limit. Long-running commands can be run in the background with the
#!bg prefix. Only available to users with the shell privilege (admins by default).python — Execute Python code
python — Execute Python code
Runs arbitrary Python in the server process. Useful for computation, data processing, and scripting. Subject to the same privilege controls as bash.
read_file / write_file / edit_file / grep / glob / ls — File access
read_file / write_file / edit_file / grep / glob / ls — File access
Read existing files, write new files, or make precise find-and-replace edits to existing files. Write and edit show a before/after diff in the tool bubble.
grep, glob, and ls provide search and directory listing without shelling out to bash. File access is subject to the configured workspace, when one is set.create_document / edit_document / update_document — Document editor
create_document / edit_document / update_document — Document editor
Create and edit documents in the Odysseus document editor panel, with full version history. Long-form content (code, reports, essays) goes here rather than the chat window.
manage_memory — Read and write persistent memory
manage_memory — Read and write persistent memory
Store and retrieve facts, preferences, and context in the ChromaDB vector store. Memory persists across sessions and is surfaced automatically when relevant.
manage_skills — Invoke reusable prompt templates
manage_skills — Invoke reusable prompt templates
List, view, and invoke Skills — reusable procedures the agent has learned. Skills are automatically matched to relevant requests and injected into context at the start of each turn.
manage_tasks — Create scheduled background tasks
manage_tasks — Create scheduled background tasks
Create cron-style tasks that run automatically on a schedule, with the agent acting on them. For recurring jobs like “summarize my inbox every morning.”
manage_notes — Notes and reminders
manage_notes — Notes and reminders
Create, read, and update notes, checklists, and timed reminders. Notes are distinct from memory — they are user-visible items, not internal context.
manage_calendar — Calendar events
manage_calendar — Calendar events
Create, list, update, and delete calendar events via the CalDAV-backed local calendar.
Email tools — list_emails, read_email, send_email, reply_to_email, and more
Email tools — list_emails, read_email, send_email, reply_to_email, and more
Full email access: list, read, send, reply, archive, delete, and bulk-operate on messages across configured IMAP/SMTP accounts.
Plan mode
Agent requests can be sent in Plan mode: the agent investigates the task with read-only tools and produces a GitHub-style checklist plan before executing anything. Once you review and approve the plan, the agent works through each step in order, ticking items off and keeping the plan window updated live.In Plan mode all write-capable tools are disabled for the planning turn. The agent can read files, search the web, and browse the project, but it cannot write files, run destructive commands, or make API calls that modify state.
MCP tool integration
In addition to built-in tools, the agent can use any tool exposed by a connected MCP server. This includes the bundled browser MCP (@playwright/mcp) for page navigation and screenshots, as well as any custom MCP server you register.
MCP tools are discovered automatically at startup and appear in the agent’s tool repertoire alongside the built-in set. For setup instructions see MCP Servers.
Permissions and privilege controls
Tool access is gated per user:| Tool | Default (non-admin) | Admin |
|---|---|---|
bash / python (shell) | ❌ | ✅ |
read_file / write_file / edit_file / grep / glob / ls | ❌ | ✅ |
web_search, web_fetch | ✅ | ✅ |
manage_memory, manage_skills | ❌ | ✅ |
manage_tasks, manage_calendar | ❌ | ✅ |
create_document, edit_document | ✅ | ✅ |
Email tools (list_emails, send_email, etc.) | ❌ | ✅ |
| MCP server tools | ❌ | ✅ |
Tips for small models
Smaller models (4k–16k context) work best with Agent mode when:- The task is scoped tightly to a single goal per message.
- You disable tools that aren’t needed (Settings → Agent Tools toggles) to reduce the system prompt size.
- You avoid very long document attachments; the context budget is shared between the system prompt, tool descriptions, and conversation history.