The 11 tools available to the daemon's AI agent — capabilities, danger levels, and approval requirements

ToolsCopy Anchor Link

The agent has access to 11 tools for interacting with the user's machine. Each tool has a danger classification that determines whether it needs user approval before execution.

Danger levelsCopy Anchor Link

The autoApprove option in agent:start can override approval requirements for safe and moderate tools. dangerous tools always require approval unless explicitly overridden.

Tool referenceCopy Anchor Link

shellCopy Anchor Link

Execute a shell command via bash -c.

{
  "tool": "shell",
  "input": { "command": "npm test -- --coverage" }
}

The shell tool spawns a bash process and streams stdout/stderr in real-time via agent:shell_output events. The agent receives the full output as the tool result.

pythonCopy Anchor Link

Execute Python code via python3 -u -c.

{
  "tool": "python",
  "input": { "code": "import json\nprint(json.dumps({'status': 'ok'}))" }
}

read_fileCopy Anchor Link

Read the contents of a file.

{
  "tool": "read_file",
  "input": { "path": "src/auth.ts", "startLine": 1, "endLine": 50 }
}

Optional startLine and endLine parameters for partial reads. Paths are resolved relative to the session's cwd.

write_fileCopy Anchor Link

Write content to a file (creates or overwrites).

{
  "tool": "write_file",
  "input": { "path": "src/utils.ts", "content": "export function add(a: number, b: number) {\n  return a + b;\n}\n" }
}

list_directoryCopy Anchor Link

List files and directories at a given path.

{
  "tool": "list_directory",
  "input": { "path": "src/components" }
}

search_filesCopy Anchor Link

Search for files matching a pattern or containing text.

{
  "tool": "search_files",
  "input": { "query": "TODO", "path": "src/", "pattern": "*.ts" }
}

open_urlCopy Anchor Link

Open a URL in the default browser.

{
  "tool": "open_url",
  "input": { "url": "http://localhost:3000" }
}

screenshotCopy Anchor Link

Capture a screenshot of the current screen.

{
  "tool": "screenshot",
  "input": {}
}

Implementation varies by platform:

• macOS: screencapture -x /tmp/screenshot.png
• Linux: import -window root /tmp/screenshot.png (ImageMagick)

Returns the screenshot as a base64-encoded PNG.

clipboard_readCopy Anchor Link

Read the current system clipboard contents.

{
  "tool": "clipboard_read",
  "input": {}
}

• macOS: pbpaste
• Linux: xclip -selection clipboard -o

clipboard_writeCopy Anchor Link

Write text to the system clipboard.

{
  "tool": "clipboard_write",
  "input": { "text": "copied content" }
}

• macOS: pipes to pbcopy
• Linux: pipes to xclip -selection clipboard

notifyCopy Anchor Link

Send a desktop notification to the user.

{
  "tool": "notify",
  "input": { "title": "Task complete", "message": "All tests passing" }
}

Tool result formatCopy Anchor Link

Every tool returns a result in this shape:

interface AgentToolResult {
  toolCallId: string;      // ID of the tool call this result belongs to
  tool: string;            // Tool name
  success: boolean;        // Whether execution succeeded
  output: string | null;   // Tool output (file contents, command output, etc.)
  error: string | null;    // Error message if failed
  durationMs: number;      // Execution time in milliseconds
}

Approval flowCopy Anchor Link

When a tool requires approval:

1. The daemon emits agent:approval_required with the tool call details
2. The session enters waiting_approval state — the agentic loop pauses
3. The client shows an approval UI (Allow / Deny buttons)
4. User decides:
   • Allow → client sends agent:approve → daemon executes the tool → loop continues
   • Deny → client sends agent:deny → daemon returns an error result to the LLM → loop continues (agent adapts)

The agent is designed to handle denials gracefully — it will try alternative approaches or ask the user for guidance.

Git worktree isolationCopy Anchor Link

When configured, the agent can run in an isolated git worktree:

~/.codmir/worktrees/{session-id}/

This creates a fresh checkout on a branch named codmir/{session-id}. The agent's file modifications are isolated from your working directory. After the session, the worktree is:

• Preserved if there are uncommitted changes (user can review and merge)
• Removed if no changes were made

This is useful for experimental or high-risk tasks where you want the agent to work without touching your main tree.