Choosing an Agent

Choose what runs in each workspace

Grove runs your existing coding agents in isolated workspaces. Claude Code, Codex and OpenCode have native adapters that let you send messages, interrupt work and answer questions from Grove without attaching to their terminal UI.

• Native session. Grove starts the agent's protocol process and keeps its control connection open between turns.
• Headless command. A standalone command such as claude -p runs without an interactive UI, but Grove does not own its control protocol.
• Interactive terminal. Grove launches the agent's usual UI in tmux. Other terminal tools, including Aider, Cursor, Gemini and a shell, use this path.

Native sessions and terminal twins

Choose native mode when you want to control Claude Code, Codex or OpenCode from Grove. Choose a headed terminal when you need the agent's own interactive UI. A standalone headless command suits a scripted task that can finish without further input.

• Native does not mean unattended permission. The agent's approval and sandbox policy still applies. A pending approval can stop progress until you respond.
• The Stream tab is a log. Grove's worker records protocol frames in the tmux pane. Attaching does not open a second agent UI.
• Recovery is separate from pause. The worker reconnects after a daemon restart without replacing its running agent. Respawn may recover history when a session ID and transcript were saved. Do not assume every native Codex restart continues its thread. Creating a native workspace with a transcript ID remains unsupported.
• Choose per workspace. Use Session mode in the web composer, the TUI checkbox, grove create --native/--terminal, or native on grove_create_workspace. The choice is saved with the workspace.
• Containers need the control connection. Native mode requires the daemon's mailbox socket to be available inside the container.

{
  "agents": [
    {"name": "claude-tui", "command": "claude", "kind": "claude_code", "native": false}
  ]
}

Mail reaches every live agent, native or interactive, through the channel Grove already steers it with. Mailbox text is untrusted agent data that cannot authorize a tool, a config change, or a bypass of native permissions.

Native adapters

Three agents have first party native adapters. All three run without the agent's interactive UI, and each page below covers its protocol, its approval support and what it cannot do.

Agent spec fields

Defaults

Grove ships seven agents, and they always merge into your roster, listed or not. See Hiding the built-ins to run a closed set instead.

Adding a custom agent

Drop the entry into your project config. Grove merges it by name, so the list extends without redefining claude or shell.

{
  "agents": [
    { "name": "aider",  "command": "aider --model sonnet" },
    { "name": "cursor", "command": "cursor-agent",         "description": "Cursor's CLI agent" },
    { "name": "gpt",    "command": "openai-agent --model gpt-4o-mini", "env": { "OPENAI_API_KEY": "${OPENAI_API_KEY}" } }
  ]
}

• New names append, matching names merge field by field, so overriding only claude's command keeps its kind. See Configuration cascade.
• A teammate drops cursor into config.local.json without disturbing the team's list. Restart grove to see it.
• Pick shell to run without an agent. Grove still creates the worktree, runs the init script and opens tmux.

Telling Grove what kind of agent it is

kind tells Grove whether it can look inside a session for the Activity Dashboard.

• claude_code, codex and opencode support native control and read transcripts for live state, turns, tokens and title.
• mewbo reads a remote session over REST, configured in the mewbo section. It is a remote adapter, not a local native process.
• generic, the default, launches the command without session introspection or native control. Use it for other terminal agents.
• A custom named Claude agent such as code-agent must declare kind: "claude_code" itself. An omitted kind silently defaults to generic with no transcript for the dashboard.

{
  "agents": [
    { "name": "code-agent", "command": "claude --model claude-opus-4-5", "kind": "claude_code" }
  ]
}

Models in the create form

The model field offers the selected agent's discovered models, plus Agent default and Custom for any id you type.

{
  "agents": [
    {
      "name": "claude",
      "models": ["sonnet", "opus", "my-gateway-model"]
    }
  ]
}

models pins, reorders or adds the ids your team wants to see. It is never a validated allowlist, and Grove forwards any id verbatim to the provider.

Hiding the built-ins

Set builtin_agents: false and your agents list becomes the whole roster, an allowlist.

{
  "builtin_agents": false,
  "agents": [
    { "name": "aider",  "command": "aider --model sonnet" },
    { "name": "cursor", "command": "cursor-agent", "description": "Cursor's CLI agent" }
  ]
}

• Name a built in bare, { "name": "claude" }, and merge by name fills in its command and kind.
• Hiding is a real gate. A hidden agent cannot create a workspace anywhere, and an existing workspace created with it cannot resume or respawn until you add it back.
• builtin_agents cascades, so a committed config can restore the roster for one repo. It is not a security boundary.
• Issue ops looks for an agent named claude. Without one, point issue ops's agent at your own.

See also

• Claude Code, Codex, OpenCode: each native adapter in depth.
• Project setup: where the agent list lives.
• Configuration cascade: merge-by-name in context.
• Agent activity and sessions: what kind unlocks.
• Container workspaces: env_file/env_command relative to an agent's own env.