Installation & Setup Usage Guide Configuration Agents & Tools MCP Servers Session Sharing ACP Integration System Architecture Embedding Guide API Reference Overview Configuration Caching Overview Payments Integration Guide OpenClaw Plugin

Agents & Tools

Built-in agents, tools reference, and customization.

Agents

otto ships with four built-in agents. Each has a system prompt and curated toolset.

build

Code generation, bug fixes, feature implementation. Most capable agent with full filesystem and shell access.

Tools: read, write, ls, tree, bash, update_todos, glob, ripgrep, git_status, terminal, apply_patch, websearch

otto ask "create an auth component" --agent build
otto ask "fix the failing test" --agent build

plan

Architecture planning and code analysis. Read-only — cannot modify files or run commands.

Tools: read, ls, tree, ripgrep, update_todos, websearch

otto ask "design the API architecture" --agent plan
otto ask "review the dependency graph" --agent plan

general

General-purpose assistant for mixed tasks.

Tools: read, write, ls, tree, bash, ripgrep, glob, websearch, update_todos

otto ask "explain how this module works" --agent general

research

Deep research across sessions and the web. Can query past sessions for context.

Tools: read, ls, tree, ripgrep, websearch, update_todos, query_sessions, query_messages, search_history

otto ask "research how auth is implemented" --agent research

All agents also receive: progress_update, finish, skill.

Tools

File System

Tool	Description
`read`	Read file contents. Supports line ranges.
`write`	Write content to a file. Creates if it doesn't exist.
`ls`	List directory contents (non-recursive).
`tree`	Render directory tree with configurable depth.
`glob`	Find files matching glob patterns.

Search

Tool	Description
`grep`	Search file contents with regex.
`ripgrep`	Fast regex search using rg.
`websearch`	Search the web or fetch URL content.

Editing

Tool	Description
`edit`	Structured file editing: replace, insert, delete.
`apply_patch`	Apply unified diff patches with fuzzy matching.

Shell

Tool	Description
`bash`	Execute shell commands. Returns stdout, stderr, exit code.
`terminal`	Persistent terminal sessions via bun-pty.

Git

Tool	Description
`git_status`	Git working tree status.
`git_diff`	Git diff (staged or all changes).
`git_commit`	Create a git commit.

Agent Configuration

Per-Project

Create .otto/agents.json in your project root:

{
  "build": {
    "tools": ["read", "write", "bash", "git_status", "ripgrep"],
    "prompt": ".otto/agents/build/agent.md"
  },
  "custom-agent": {
    "tools": ["read", "ls", "tree", "ripgrep"],
    "prompt": ".otto/agents/custom-agent/agent.md"
  }
}

Options

Field	Description
`tools`	Override the default tool list.
`appendTools`	Add tools to the default list.
`prompt`	Path to a custom system prompt file.
`provider`	Override provider for this agent.
`model`	Override model for this agent.

Custom Tools

Add project-specific tools in .otto/tools/:

// .otto/tools/deploy.ts
import { tool } from "@ottocode/sdk";
import { z } from "zod";

export default tool({
  name: "deploy",
  description: "Deploy the application",
  parameters: z.object({
    environment: z.enum(["staging", "production"]),
  }),
  execute: async ({ environment }) => {
    return { success: true, environment };
  },
});

Skills

Skills are markdown files that provide specialized instructions to agents, loaded via the skill tool.

Defined at three levels:

Project: .otto/skills/
Global: ~/.config/otto/skills/
Built-in: bundled with otto

otto skills                    # list available skills