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 or telemetry, 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

  // OpenTelemetry trace export. When enabled, every LLM call is emitted as a
  // generation span (gen_ai.* attributes) to an OTLP/HTTP backend such as
  // Langfuse — any OTLP-compatible platform works (Phoenix, Jaeger, …).
  // Each span is tagged with the current session id (langfuse.session.id +
  // session.id), so a run's calls — main agent and sub-agents — group into one
  // session on the backend automatically; no extra config needed.
  // endpoint is the full OTLP *traces* URL, used as-is: it must already include
  // the /v1/traces path (it is NOT auto-appended). For Langfuse Cloud:
  //   EU https://cloud.langfuse.com/api/public/otel/v1/traces
  //   US https://us.cloud.langfuse.com/api/public/otel/v1/traces
  // public_key/secret_key form HTTP Basic auth (base64 of "public:secret").
  "telemetry": {
    "enabled": false,
    "endpoint": "https://cloud.langfuse.com/api/public/otel/v1/traces",
    "public_key": "pk-lf-...",
    "secret_key": "sk-lf-..."
  },

  // 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 only constrained at launch (workdir) and never guarantees actual access scope — always requires approval.
  // 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
  //   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": []
  },

  // MCP servers: stdio (local process) or http (remote endpoint). ${VAR} in
  // env and headers takes from codebot's environment in your settings alone.
  "mcp_servers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "remote-api": {
      "type": "http",
      "url": "https://mcp.deepwiki.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"
  ]
}