Agents Settings

Spruce works with any MCP-capable agent CLI you already use — Claude Code, Codex, OpenCode, Gemini, Kiro, or something custom. Settings → Agents is where you pick which one runs by default, see what Spruce can detect on this machine, and (for agents that need it) write the Spruce MCP server into their global config.

Settings → Agents page showing agent cards and the Spruce MCP Server section

Default agent

Each action ships with a modes: map keyed by agent name (claude, codex, gemini, kiro, opencode, and so on — plus shell for non-agent commands). When you run an action, Spruce picks the mode that matches your default agent setting. Switch the default and every action automatically routes to the new agent — no editing per-action files.

Pick a default by clicking one of the agent cards at the top of the page. Cards are clickable when the agent is both installed and (if it requires global MCP config) already configured; cards for agents Spruce can't run yet are dimmed.

Card states

You can pop open the × on a Globally configured badge to remove Spruce from that agent's global config — useful if you want to stop the agent from auto-discovering Spruce's tools.

Why some agents need global config and others don't

Two delivery paths for MCP config, depending on the agent CLI:

• Per-session, inline. Claude Code, Codex, OpenCode, and Gemini all accept MCP config at launch time — through a flag, an env var, or a settings file Spruce writes per session. There's nothing to set up; every session inherits a fresh MCP config pointing at the Spruce CLI.
• Global config file. Kiro reads MCP servers from ~/.kiro/settings/mcp.json once at startup. Spruce can't inject config at launch, so it writes the spruce entry into that file when you click Set up MCP. Removing Spruce or moving the bundled CLI changes the path, hence the Stale path state.

The card layout makes this concrete: agents in the first group never need a setup button, agents in the second group do.

Spruce MCP Server

Below the agent list, the Spruce MCP Server section gives you the raw snippet to wire any other MCP-capable CLI into Spruce by hand.

• Command — the absolute path to the bundled spruce-cli plus the mcp serve subcommand. Most MCP clients ask for these as a separate command + args list.
• Copy as JSON — JSON snippet you can paste into Claude Code (--mcp-config), the Kiro settings file, the Gemini settings file, or anything else that takes JSON-shaped MCP config.
• Copy as TOML — TOML snippet for Codex (mcp_servers.spruce).

If the bundled CLI can't be located (rare; usually only on dev builds), Spruce surfaces a warning and the snippets fall back to the literal string "spruce-cli" — your config is still valid as long as spruce-cli is on your PATH.

Where else you'll see this

• Welcome wizard. First-run setup includes an Agent step that uses the same card list. Pick a default there to skip the trip to Settings later.
• Action editor. Editing a project action (under Settings → Actions) lets you add or remove individual modes — e.g. drop the Codex mode if you'll never use it on this project, or wire up a custom mode for a CLI Spruce doesn't bundle.
• {{sidecar_path}} in action modes. Actions reference the same Spruce CLI binary via {{sidecar_path}} so per-session MCP config works without hard-coded paths. See Action Template Variables.

Related

• Actions — how the modes: map drives which agent runs an action.
• Action Template Variables — {{sidecar_path}} and {{session_file:<name>}}, the placeholders MCP setup relies on.
• MCP Tools — what Spruce exposes to an agent over MCP.
• Global Preferences — the rest of the app-wide settings page.