settings.example.jsonc

{
  // ~/.codebot/settings.json is yours; .codebot/settings.json at a project's
  // root sets fields over it. A project never sets providers, search_provider,
  // search_api_key, langfuse or sandbox, and each of its hooks, mcp_servers, plugins,
  // permissions.allow rules and roots takes effect only once you trust it
  // (/trust).
  //
  // Default provider/model. /model saves its choice here, in your file.
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "reasoning_effort": "",   // "" = provider default; off | low | medium | high | xhigh | max

  // Per-provider credentials and model catalog.
  // Provider names are free-form; use "type" to specify the API protocol.
  "providers": {
    "anthropic": {
      "api_key": "",
      "models": ["claude-sonnet-4-6", "claude-opus-4-6"],
      "small_model": "claude-haiku-4-5"  // sub-agents model; omit to use main model
    },
    "openai": {
      "api_key": "",
      "base_url": "",
      // Optional OpenAI protocol endpoint: chat (default, /v1/chat/completions)
      // or responses (/v1/responses). Codex-style proxies usually need responses.
      "api": "chat",
      "models": ["gpt-5.4", "gpt-5.3-codex"],
      "small_model": "gpt-5-mini"
    },
    "openrouter": {
      "api_key": "",
      "base_url": "https://openrouter.ai/api/v1",
      "small_model": "stepfun/step-3.5-flash:free",
      "models": ["stepfun/step-3.5-flash:free", "openrouter/hunter-alpha", "openrouter/healer-alpha"]
      // no small_model — sub-agents will use the main model
    },
    "gemini": {
      "api_key": "",
      "models": ["gemini-3.1-pro", "gemini-2.5-flash"],
      "small_model": "gemini-2.5-flash"
    },
    "deepseek": {
      "api_key": "",
      "models": ["deepseek-chat", "deepseek-reasoner"],
      "small_model": "deepseek-chat"
    },
    // Claude on Amazon Bedrock through its Messages API, which takes Anthropic's
    // request format: deferred tools and the other Claude features work as with
    // Anthropic. The api_key is a Bedrock API key. Bedrock's Converse API
    // (type "bedrock") cannot defer tools, so prefer this for Claude.
    "bedrock-claude": {
      "type": "anthropic",
      "api_key": "",
      "base_url": "https://bedrock-mantle.us-east-1.api.aws/anthropic",
      "models": ["anthropic.claude-opus-5-5", "anthropic.claude-sonnet-5-5"],
      "small_model": "anthropic.claude-haiku-4-5"
    },
    // Custom proxy example: "type" specifies the API protocol (openai/anthropic/gemini).
    // Omit "type" for well-known provider names — it will be inferred automatically.
    // Optional "extra" is provider-level litellm config for proxies that check
    // client headers; it is sent as HTTP/client config, not request body fields.
    "my-proxy": {
      "type": "anthropic",
      "api_key": "sk-xxx",
      "base_url": "https://proxy.example.com",
      "models": ["claude-sonnet-4-6"],
      "small_model": "claude-haiku-4-5",
      "extra": {
        "user_agent": "claude-code/2.1.183",
        "anthropic_beta": "claude-code-20250219",
        "headers": {
          "X-Stainless-Lang": "js",
          "X-Stainless-Package-Version": "0.94.0",
          "X-Stainless-Runtime": "node"
        }
      }
    },
    "codex-proxy": {
      "type": "openai",
      "api": "responses",
      "api_key": "sk-xxx",
      "base_url": "https://proxy.example.com/v1",
      "models": ["gpt-5.4", "gpt-5.4-mini"],
      "small_model": "gpt-5.4-mini",
      "extra": {
        "user_agent": "codex-tui/0.142.3",
        "headers": {
          "Originator": "codex-tui",
          "Session_id": "replace-with-random-session-id"
        }
      }
    },
    // Company gateway (a LiteLLM gateway): codebot runs the agent, e.g. in a
    // sandbox, while the gateway holds the provider keys, makes the model calls and
    // bills them. "api_key" is codebot's token for the gateway (sent as Bearer).
    "corp-gateway": {
      "type": "gateway",
      "api_key": "sandbox-token",
      "base_url": "https://llm-gateway.internal/agent",
      "models": ["claude-sonnet-4-6", "gpt-5"],
      "small_model": "claude-haiku-4-5"
    }
  },

  "max_turns": 30,

  // Cap the effective compaction window: effective = min(detected, compact_window).
  // Useful for forcing earlier compaction on 1M-window models that suffer attention decay past ~200k.
  // Never exceeds the model's real window. Omit / 0 = use detected window.
  "compact_window": 300000,
  "compact_ratio": 0.85,

  "search_provider": "tavily", // tavily (needs a key) | jina
  "search_api_key": "", // else TAVILY_API_KEY / JINA_API_KEY

  // Langfuse: the keys of a project turn tracing on. Each turn is a trace of
  // what the model saw and said, the tool calls with their approvals and
  // results, and the sub-agents, grouped by conversation as Langfuse
  // sessions, with the cost of each call. Compacting, /btw and the input
  // suggestions are traces of their own. Inputs and outputs are recorded in
  // full, credentials recognizable by their form (API keys, tokens, private
  // keys) cut out, so point it at a project you trust with your code:
  // Langfuse Cloud or your own instance. Unset fields fall back to
  // LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY and LANGFUSE_BASE_URL, as a
  // project's settings hand them out.
  "langfuse": {
    "public_key": "", // pk-lf-...
    "secret_key": "", // sk-lf-...
    "base_url": "https://cloud.langfuse.com" // US https://us.cloud.langfuse.com, or your own instance
  },

  // Hooks: commands/prompts/http triggered on lifecycle events.
  // Yours and those of a project you trusted to them all run: they are
  // appended, not replaced.
  // A hook may print JSON to stdout to influence the run:
  //   {"block": true, "reason": "..."}   block the action (blocking hooks only)
  //   {"updated_input": { ... }}         rewrite tool args (PreToolUse)
  //   {"additional_context": "..."}      inject context into the turn (UserPromptSubmit)
  // For command hooks, exit code 2 also blocks; any other non-zero exit is a
  // non-blocking error (logged, never stops the run).
  // A command hook runs in sh. On Windows, command_windows, if given, runs in
  // PowerShell instead; without it, the hook needs sh on PATH (Git for
  // Windows has one). PowerShell turns exit codes other than 0 and 1 into 1:
  // end a command that blocks by exiting 2 with "exit $LASTEXITCODE".
  "hooks": {
    "PreToolUse": [
      { "type": "command", "command": "echo $HOOK_TOOL_NAME >> ~/.codebot/audit.log", "matcher": "bash", "blocking": true, "timeout": 10 }
    ],
    "UserPromptSubmit": [
      { "type": "command", "command": "echo '{\"additional_context\":\"Repo convention: run gofmt before committing.\"}'" }
    ],
    "PostToolUse": [
      { "type": "command", "command": "echo done" }
    ],
    "Notification": [
      { "type": "command", "command": "notify-send 'codebot' 'Agent finished'",
        "command_windows": "[console]::beep(880, 200)" }
    ]
  },

  // Filesystem authorization roots.
  // Defaults: read_roots / write_roots both contain only the current working directory ".".
  // Add extra directories explicitly; write_roots should usually be stricter than read_roots.
  // Relative roots are taken from the working directory in your settings, and from the
  // project's root in a project's.
  // Note: roots strictly govern file tools (read/write/edit/glob/grep/ls).
  // bash is constrained at launch (workdir), and a read-only command such as cat
  // runs unasked only on files in read_roots; unless the sandbox below is on, what
  // else a command touches is up to your approval. With the sandbox, it writes only
  // in the workspace, the write_roots and the temp directory.
  // web_fetch asks for each host until you allow it.
  // allow / deny take rules; a deny rule wins over an allow rule:
  //   web_fetch                    a tool, by name; a trailing * matches a prefix
  //   Bash(go test *)              a command, by its words; * stands for the rest. An allow
  //                                rule covers that command alone, with nothing to expand or
  //                                redirect to a file; a deny rule any command a line runs
  //   Read(src/**), Edit(src/**)   a path, relative to a root or absolute (Write as Edit)
  //   WebFetch(*.example.com)      web_fetch of a host; *. takes in its subdomains
  "permissions": {
    "read_roots": [
      ".",
      "../shared"
    ],
    "write_roots": [
      "."
    ],
    "allow": [],
    "deny": []
  },

  // Runs the model's shell commands in an OS sandbox (Seatbelt on macOS,
  // bubblewrap on Linux): they read all but credentials, write only in the
  // workspace, the write_roots and the temp directory, but not to git's
  // directory or anything else that runs later unasked, and reach no
  // network, localhost included, unless "network" is true. With the network
  // off they run without asking in balanced and accept-edits modes; one the
  // sandbox blocks may be retried outside it, which is asked about. codebot
  // stops if the sandbox cannot start. Yours alone: a project's is ignored.
  "sandbox": {
    "enabled": false,
    "network": false
  },

  // MCP servers: stdio (local process) or http (remote endpoint). ${VAR} in
  // env, headers and oauth.client_secret takes from codebot's environment in
  // your settings alone.
  "mcp_servers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    // Without an Authorization header, an HTTP server signs in with OAuth:
    // pick it in /mcp.
    "oauth-api": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    },
    // An authorization server that takes no client metadata document, such
    // as GitHub's, wants an OAuth app registered with it, its callback URL
    // http://127.0.0.1/callback.
    "registered-api": {
      "type": "http",
      "url": "https://mcp.example.org/mcp",
      "oauth": { "client_id": "your-client-id", "client_secret": "${MCP_CLIENT_SECRET}" }
    },
    "remote-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer your-token-here" }
    }
  },

  // Plugins in the Agent Plugins format: git repositories, //dir naming a
  // plugin's directory in one and #ref a branch, tag or commit, or
  // directories relative to this file. /plugins add, install, update and
  // remove manage the list; what each runs waits for you to agree to it.
  "plugins": [
    "github.com/acme/release-tools#v1.2.0",
    "github.com/acme/plugins//plugins/lint#main",
    "./plugins/local-kit"
  ]
}