agent-code Documentation

Configuration loads from three layers (highest priority first):

1. CLI flags and environment variables
2. Project config — .agent/settings.toml in your repo
3. User config — ~/.config/agent-code/config.toml

Full config reference

# ~/.config/agent-code/config.toml

[api]
base_url = "https://api.anthropic.com/v1"
model = "claude-sonnet-4-20250514"
auth_mode = "api_key"        # "api_key" or "codex_chatgpt"
# api_key is resolved from env: AGENT_CODE_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY
max_output_tokens = 16384
thinking = "enabled"          # "enabled", "disabled", or omit for default
effort = "high"               # "low", "medium", "high"
max_cost_usd = 10.0           # Stop session after this spend
timeout_secs = 120
max_retries = 3

[permissions]
default_mode = "ask"          # "ask", "allow", "deny", "plan", "accept_edits"

[[permissions.rules]]
tool = "Bash"
pattern = "git *"
action = "allow"

[[permissions.rules]]
tool = "Bash"
pattern = "rm *"
action = "deny"

[ui]
markdown = true
syntax_highlight = true
theme = "dark"
inherit_fg = false             # When theme = "auto", inherit the terminal's foreground color

# MCP servers (see MCP Servers page)
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path"]

# Lifecycle hooks (see Hooks page)
[[hooks]]
event = "post_tool_use"
tool_name = "FileWrite"
[hooks.action]
type = "shell"
command = "cargo fmt"

Auto theme detection

When [ui].theme = "auto", agent-code asks the terminal for its default colours via the OSC 10 (foreground) and OSC 11 (background) escape sequences. Both queries fire as a single batch terminated by a DA1 sentinel, so detection costs one round-trip on supported terminals (Ghostty, kitty, Alacritty, iTerm2, WezTerm, modern xterm). The reply is parsed with BT.709 luminance to pick between the dark (midnight) and light (daybreak) palettes.

Detection is skipped silently when stdin/stdout are not a terminal (in agent --serve, when output is piped, or under CI), and falls back to dark when the terminal does not respond.

inherit_fg

[ui].inherit_fg = true (default false) tells the Auto theme to replace its text slot with the foreground colour the terminal reported via OSC 10, instead of the theme's hardcoded value. Useful when you have a custom terminal palette and want plain prose to keep your usual reading colour.

Caveats:

• The override only applies when theme = "auto". Picking an explicit theme is taken at face value.
• Some terminals reply to OSC 10 with the colour they would otherwise use, even when the user has installed a colour scheme that overrides it. If your foreground looks wrong, set inherit_fg = false.
• Contrast against the (theme-chosen) background is your concern when this option is enabled.

Project config

Create .agent/settings.toml in your repo root for project-specific settings. These override user config but are overridden by CLI flags.

Initialize with:

agent
> /init
Created .agent/settings.toml

Environment variables

Codex ChatGPT auth

If you are already signed in with OpenAI Codex, agent-code can reuse that ChatGPT session without writing an API key to agent-code config:

codex login
agent --auth-mode codex_chatgpt --model gpt-5.4

Or configure it:

[api]
auth_mode = "codex_chatgpt"
model = "gpt-5.4"

This reads $CODEX_HOME/auth.json (or ~/.codex/auth.json) and uses the Codex ChatGPT backend. Set codex_home = "/path/to/.codex" under [api] or AGENT_CODE_CODEX_HOME when the Codex home is not the default.