Agents, providers & plugins

#Supported agents

Run baton agents to see what's installed and logged in on your machine (and how: "Claude subscription", "API key", …). baton login [agent] runs that agent's own sign-in (claude auth login, codex login, opencode auth login, …); Baton never sees the credentials.

#Signing in, and your Claude subscription

Baton runs each agent's own, unmodified CLI with your own login — exactly how you'd use it in a terminal. Logged in to Claude Code with a Claude Pro/Max/Team plan? The claude agent uses it; nothing else to set up.

What Baton deliberately does not do: read Claude Code's OAuth token (from the Keychain, ~/.claude, or CLAUDE_CODE_OAUTH_TOKEN) to call Anthropic's API from anything else — including Baton's own baton agent. Anthropic's terms reserve subscription credentials for Claude Code and Anthropic's apps and forbid third-party tools from routing requests through them or collecting the tokens (Legal and compliance → Authentication and credential use). The same applies to ChatGPT logins in Codex. The baton agent instead finds credentials you provisioned for API use: API keys in your environment, API-key entries in Codex's or OpenCode's auth files, or a local Ollama / LM Studio — see native-agent.md.

"Queued" means a message sent while the agent is busy is delivered as soon as its current turn ends, or immediately if you ask for interrupt delivery.

#What each adapter maps

All adapters emit the same events:

• streamed text and reasoning
• tool calls, titled the way the agent's own UI titles them (Read(src/app.ts), Ran git diff --stat)
• edit diffs with real line numbers, and terminal output with exit codes
• the agent's plan or todo list, which drives the progress % on its card
• token usage and cost where the agent reports it
• permission requests

Codex sometimes edits files with shell commands (sed -i) instead of patches. The Codex adapter snapshots the workspace with a private git index after such commands, so those edits still show up as diffs.

#Adding agents without code

Any ACP agent works through config:

[agents.my-agent]
adapter = "acp"
command = "my-agent"
args = ["--acp"]
env = { MY_AGENT_TELEMETRY = "0" }

Then /spawn my-agent, or let the orchestrator use it with spawn_agent(adapter: "my-agent"). Profiles can wrap built-in adapters too (adapter = "codex" with a different model, role, approval mode or provider).

Any CLI that takes a prompt as an argument works the same way:

[agents.mytool]
adapter = "exec"
command = "mytool"
args = ["run", "--quiet", "{prompt}"]     # {prompt} {model} {cwd}

#Model providers

A provider describes where a model comes from. It's separate from the adapter, which is the agent harness that runs it.

[providers.openrouter]
kind = "openai-compatible"
base_url = "https://openrouter.ai/api/v1"
api_key = "env:OPENROUTER_API_KEY"
models = { kimi = "moonshotai/kimi-k2" }

[agents.cheap-coder]
adapter = "opencode"
provider = "openrouter"
model = "kimi"

Each adapter translates the provider into whatever its agent understands:

• Claude: ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN (Anthropic-compatible endpoints), or Bedrock/Vertex variables.
• Codex: -c model_providers.*.
• OpenCode: an injected provider config.
• ACP agents: the model is set through session/set_model or config options; ACP has no way to pass provider credentials.

Secrets can be env:VAR, cmd:pass show openrouter, keychain:<service> (macOS), or a literal value. They're resolved when the agent starts and never written to the event log.

#Recipes

Recipes are reusable orchestration workflows: /recipe <name> <task>, the gallery (/recipes), or baton run "/recipe best-of-3 …". Built in: best-of-3, plan-execute, research-implement, implement-review, debug-hypotheses, test-first, shard. Add your own as Markdown in .baton/recipes/ or ~/.config/baton/recipes/:

---
name: release
description: Our release checklist
agents: 2 workers
---
Prepare release {task}: bump versions, update CHANGELOG.md, run the full test suite, and have a second agent review.

#Writing an adapter plugin

// .baton/plugins/echo.ts — plugins need no runtime imports (types are erased), so they run
// from any folder and from the compiled `baton` binary.
import type { AgentAdapter, BatonPlugin } from "@batonsh/sdk"

const id = () => crypto.randomUUID()

const echo: AgentAdapter = {
  id: "echo",
  displayName: "Echo",
  family: "custom",
  binaries: [],
  async detect() {
    return { installed: true, auth: "ok", protocols: ["in-process"] }
  },
  capabilities() {
    return { steer: false, interrupt: true, resume: false, fork: false, diff: false, usage: false, cost: false, permissions: false, mcp: false, models: [] }
  },
  async start(cfg, ctx) {
    ctx.emit({ type: "agent.status", data: { status: "ready" } })
    return {
      async prompt({ text }) {
        const turnId = id()
        ctx.emit({ type: "turn.started", data: { turnId, prompt: text } })
        ctx.emit({ type: "message.completed", data: { messageId: id(), role: "assistant", text: `echo: ${text}` } })
        ctx.emit({ type: "turn.completed", data: { turnId, stopReason: "end_turn" } })
      },
      async interrupt() {},
      async respondPermission() {},
      resumeId: () => undefined,
      async close() {
        ctx.emit({ type: "agent.exited", data: { code: 0 } })
      },
    }
  },
}

export default { name: "echo", adapters: [echo] } satisfies BatonPlugin

# .baton/config.toml
plugins = ["./.baton/plugins/echo.ts"]

Plugins listed in the global config load automatically. Plugins listed in a project config run code that came with the repository, so they only load after you run baton trust in that project. Trust is pinned to the plugin file's content: if it (or the list) changes, you have to trust it again. baton trust --revoke undoes it. See configuration.md for the other settings that need trust.

Adapter checklist (packages/adapters/testkit has startHarness and a shared contractSuite):

• emit turn.started/turn.completed around every prompt, and agent.status busy/ready
• emit tool.call then tool.update, with kind, a human-readable title, and diff / terminal content
• emit permission.requested and wait for respondPermission(requestId, optionId); when interrupted, answer null
• accept cfg.mcpServers (streamable HTTP). That's how your agent gets the baton bus tools
• never kill the agent mid-turn when interrupt() is available

#The bus tools every agent gets

Calls to these tools are approved automatically. Baton's own coordination never waits for a human.