Agent Backends

Gru uses a pluggable agent architecture. Each backend implements the AgentBackend trait, which normalizes different CLI tools into a common event stream that Gru can monitor, log, and act on.

Available Backends

Claude Code (default)

Claude Code is the default backend.

Install

npm install -g @anthropic-ai/claude-code

Verify

claude --version
claude --help

Configure

No configuration is required — Gru uses Claude Code by default. Optionally override the binary path in ~/.gru/config.toml:

[agent.claude]
binary = "/usr/local/bin/claude"

How Gru Uses It

Gru spawns Claude Code in non-interactive mode with stream JSON output:

claude --print --verbose --session-id <uuid> --output-format stream-json --dangerously-skip-permissions --include-partial-messages "<prompt>"

Key flags:

• --print — non-interactive (prints to stdout and exits)
• --verbose — include tool calls in output
• --output-format stream-json — real-time event stream
• --dangerously-skip-permissions — autonomous operation
• --session-id <uuid> — maintain context across resumes

OpenAI Codex

Codex CLI is an alternative backend using OpenAI models.

Install

npm install -g @openai/codex

Authenticate

Set your OpenAI API key:

export OPENAI_API_KEY="sk-..."

Verify

codex --version
codex --help

How Gru Uses It

Gru spawns Codex in full-auto mode with JSON output:

codex exec --json --full-auto "<prompt>"

Resume support uses:

codex exec resume --last --json --full-auto "<prompt>"

Note: Codex does not support interactive resume (gru attach will not work with Codex minions). Codex also ignores the session_id parameter — it relies on its own session persistence for both new and resumed sessions.

Selecting a Backend

Per-command

Use the --agent flag on any command that spawns an agent:

gru do 42 --agent codex
gru review 42 --agent codex
gru prompt my-prompt --agent codex

As default

Set the default in ~/.gru/config.toml:

[agent]
default = "codex"

The --agent flag always overrides the config default.

Feature Comparison

Adding a New Backend

To add a new agent backend:

1. Create src/<name>_backend.rs implementing the AgentBackend trait from src/agent.rs
2. Register it in src/agent_registry.rs (add to AVAILABLE_AGENTS and the match in resolve_backend)
3. Map the backend's output format to AgentEvent variants in parse_events()

The AgentBackend trait requires:

• name() — human-readable identifier
• build_command() — construct the CLI command for a new session
• parse_events() — convert stdout lines to normalized AgentEvents
• build_resume_command() — (optional) construct command to resume a session
• build_interactive_resume_command() — (optional) construct command for gru attach; return None to disable attach support