TOML Config

Cosine CLI can be configured through multiple sources: TOML configuration files, command-line flags, and environment variables. This guide covers user config, repository config, and MCP config as separate files because each file has its own schema.

Quick Navigation

• Configuration priority
• File locations
• Example configs
• Section reference
• Environment variables
• Best practices

Example Configs

User config

Your personal settings and global preferences. Keep this file private because it can contain provider preferences and local project mappings.

# ============================================================
# COSINE CLI USER CONFIGURATION (~/.cosine/config.toml)
# ============================================================

# ------------------------------------------------------------
# AUTHENTICATION
# ------------------------------------------------------------
# Credentials (user_id, token, team_id, team_name, team_slug) are stored
# in ~/.cosine/auth.json and are NOT written to config.toml. Only provider
# preferences live here.

# OpenAI OAuth for ChatGPT subscription users
[auth.openai]
auth_method = "oauth"
oauth_redirect_uri = "http://localhost:1455/auth/callback"

# GitHub Copilot subscription users
[auth.copilot]
auth_method = "copilot"

# ------------------------------------------------------------
# API & INFERENCE
# ------------------------------------------------------------
[api]
base_url = "https://api.cosine.sh"

[inference]
base_url = "https://api.cosine.sh"
model = "gpt-5.5"
model_selection_id = "cosine:gpt-5.5"
small_model = "claude-sonnet-4-6-1m"
micro_model = "claude-haiku-4-5"
review_model = "gemini-3.1-pro"
max_context_tokens = 128000
max_turns = 100

# ------------------------------------------------------------
# GENERAL SETTINGS
# ------------------------------------------------------------
[config]
system_prompt_id = "lumen"
reasoning_level = "medium"
mode = "auto"
shell = "/bin/zsh"
agent_commits = true
api_sessions = true
ghost_text_enabled = true
memory_recall_mode = "every"
memory_recall_detail = "snippet"
theme = "dark"
overview_graph_mode = "tokens"
runner_background_theme = "spinner"

# ------------------------------------------------------------
# BROWSER & MCP
# ------------------------------------------------------------
[browser]
cdp_url = "http://localhost:9222"
tool_backend = "browser"

# ------------------------------------------------------------
# ULTRA DAEMON (Background task suggestions)
# ------------------------------------------------------------
[ultra.inactivity_minutes]
repo = 15
gmail = 5

# ------------------------------------------------------------
# PROJECT MAPPINGS
# ------------------------------------------------------------
[projects]
"/Users/me/work/api" = { project_id = "proj_abc123" }

# ------------------------------------------------------------
# TOOL CONFIGURATION
# ------------------------------------------------------------
[agent]
disabled_tools = ["edit"]

Repository config

Deprecated project automation configuration, retained for compatibility with hooks, LSP, extra context, and project skills/initialization. It does not configure profiles, authentication, inference, or models. It is safe to commit when it contains no secrets.

# Mark as topmost in monorepos (stops searching parent dirs)
is_topmost_config = true

[agent]
extra_context = "AGENTS.md"

[hooks]

[[hooks.on_save]]
matcher = "edit"
command = "npm run lint -- --fix {file}"
async = false

MCP config

External tool integrations via Model Context Protocol.

{
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/user/projects"
      ]
    },
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxx"
      }
    }
  }
}

Configuration Priority

Runtime flags have highest priority, followed by values in the selected personal profile and then build/code defaults. For model selection specifically, the order is runtime model override, profile model, then build/code default. Repository config no longer sets the model.

Some environment variables are not simple defaults. COSINE_CONFIG_FILE selects the user config file path before loading, and COSINE_AUTH_* variables override credentials loaded from ~/.cosine/auth.json.

Configuration File Locations

File	Purpose	Scope
config.toml	Default personal profile	User-wide
config.<profile>.toml	Named personal profile	User-wide
.cosine.toml or cosine.toml	Deprecated project automation compatibility	Repository
mcp.json	MCP server definitions	User-wide

Profile-Specific Configs

These files live in the platform-specific Cosine config/home directory (typically ~/.cosine on macOS and Linux). Create multiple personal profiles for different contexts:

# Use the default profile (config.toml)
cos

# Use the work profile (config.work.toml)
cos --profile work

Named repository files such as cosine.work.toml are unsupported. If an explicitly selected profile is missing, startup fails and reports its expected path, available profiles, and commands to create it or return to the default profile.

cos configure selects the profile before prompting for settings. Profile selection uses an explicit --profile flag first, then the target profile value, then the product default.

Configuration Sections Reference

The sections below cover the TOML keys you are most likely to edit directly.

[auth] — Authentication

Auth credentials (user_id, token, team_id, team_name, team_slug) are stored in ~/.cosine/auth.json (mode 0600) and are never written to config.toml. They are managed automatically by cos login / cos logout. Manual configuration is rarely needed; to override at runtime use the COSINE_AUTH_TOKEN, COSINE_AUTH_USER_ID, COSINE_AUTH_TEAM_ID, COSINE_AUTH_TEAM_NAME, and COSINE_AUTH_TEAM_SLUG environment variables.

The [auth] TOML section is reserved for provider preferences only:

Field	Type	Description
auth.openai.auth_method	string	"cosine" or "oauth"
auth.openai.oauth_redirect_uri	string	OAuth callback URL
auth.copilot.auth_method	string	"copilot" for GitHub Copilot-backed models

[api] — Cosine API

Field	Type	Default	Description
base_url	string	https://api.cosine.sh	Base URL for Cosine API

[inference] — LLM Settings

Field	Type	Default	Description
base_url	string	https://api.cosine.sh	OpenAI-compatible endpoint
model	string	lumen-outpost	Default agent model
model_selection_id	string	derived from model	Provider-qualified model ID, such as cosine:gpt-5.5
small_model	string	claude-sonnet-4-6-1m	Fast model for quick tasks
micro_model	string	claude-haiku-4-5	Tiny model for memory queries
review_model	string	gemini-3.1-pro	Model for code reviews
max_context_tokens	int	0 (no override)	Max context window; values at or below 0 are ignored
max_turns	int	0 (no override)	Max conversation turns; values at or below 0 are ignored

Available model IDs include: cosine:auto, cosine:lumen-outpost, cosine:gpt-5.5, cosine:gpt-5.4, cosine:claude-sonnet-4-6-1m, cosine:gemini-3.1-pro, ChatGPT-backed IDs such as chatgpt:gpt-5.5, Claude Max IDs such as claudemax:claude-sonnet-4-6, and Copilot IDs such as copilot:gpt-5.5.

[config] — General Settings

Field	Type	Default	Description
system_prompt_id	string	lumen	Default prompt: lumen, judge, orchestrator
reasoning_level	string	medium	none, low, medium, high, xhigh, adaptive, or max
mode	string	manual	Startup mode: manual, auto, plan, swarm; normal also maps to manual
shell	string	detected	Preferred shell for terminal sessions
agent_commits	bool	true	Auto-create Agent Commits per turn
agent_browser_enabled	bool	false	Expose browser-control tools; configurable from Command Centre Settings
agent_desktop_enabled	bool	false	Expose foreground desktop-control tools; configurable from Command Centre Settings
api_sessions	bool	true	Enable API-backed session persistence and remote resume
auto_accept	bool	false	Persisted default auto-accept preference
ghost_text_enabled	bool	true	Enable inline autocomplete suggestions in the TUI
memory_recall_mode	string	first	first or every (when to recall memory)
memory_recall_detail	string	snippet	snippet or full (memory detail)
theme	string	dark	UI theme, typically dark or light
overview_graph_mode	string	tokens	Overview graph mode: tokens or resources
runner_background_theme	string	spinner	Runner background motion: spinner, blue-shift, knight, bloom, runway, twin-beam, ripple, or aurora
runner_background_color	string	unset	Runner color key: unset/default, theme names, mode, or session

The legacy agent_computer_enabled key is migrated to agent_desktop_enabled when the canonical key is absent. | latex_formatting | bool | false | Persisted LaTeX formatting preference | | ultra_enabled | bool | false | Enable Ultra daemon | | on_the_go_enabled | bool | false | Enable the Desktop On the Go listener |

Autocomplete suggestions: Toggle from the TUI with /autocomplete or through Settings → Autocomplete. When ghost_text_enabled = false, Cosine does not request background autocomplete suggestions.

Reasoning levels: none (minimal internal reasoning), low (fast), medium (balanced), high (thorough), xhigh (supported GPT/Codex models), adaptive (supported Claude models), max (supported models only)

For guidance on when to use each level, see Reasoning.

Older configs that still use checkpointing are still read, but new configs should use agent_commits.

telemetry.enabled is not a configurable opt-out. Telemetry is enabled after config load even if a config file sets it to false.

Shell paths:

• Bash: /bin/bash
• Zsh: /bin/zsh
• Fish: /opt/homebrew/bin/fish

[computer.browser] — Browser Automation

Field	Type	Description
enabled	boolean	Allow browser automation when the session is started with --enable-agent-browser
executable_path	string	Optional path to Chrome, Chromium, or Brave
cdp_url	string	Optional Chrome DevTools URL, e.g. http://localhost:9222; attached browsers keep their launch mode
launch_mode	string	Local browser mode: auto (default), headless, or headful
allowed_domains	array	Optional list of domains the browser may visit

You can change launch_mode from the Command Centre Settings tab. A mode change applies to the next locally launched browser; it does not restart an existing browser.

[ultra.inactivity_minutes] — Ultra Daemon

Minutes of inactivity before suggesting tasks from each source:

[ultra.inactivity_minutes]
repo = 15      # Local coding (default: 15)
slack = 0      # Slack MCP server
github = 0     # GitHub MCP server
linear = 0     # Linear MCP server
gmail = 5      # Gmail

User [agent] — Tool Configuration

In ~/.cosine/config.toml, [agent] controls user-wide tool settings.

Field	Type	Description
disabled_tools	array	Tools to disable: ["edit", "mcp_*"]

Tool rules:

• Exact match: "edit"
• Wildcard: "mcp_*" (disables all MCP tools)

Manage via terminal user interface (TUI): Press Ctrl+P → Tools → Space to toggle

Repository [agent] — Deprecated project automation

In .cosine.toml or cosine.toml, [agent] retains extra-context compatibility for project automation.

Field	Type	Description
extra_context	string	Path to context file (e.g., AGENTS.md)

The legacy camelCase key extraContext is still read, but new repo configs should use extra_context.

[hooks] — Automation

Field	Type	Description
on_save	array(table)	One or more [[hooks.on_save]] entries that run after file writes

Each hook entry supports:

Field	Type	Description
matcher	string	Regex matched against the tool name. Use "edit" to cover edit, apply_patch, and find_replace_in_file.
directories	array(string)	Optional directory prefixes, relative to the config root.
extensions	array(string)	Optional file extensions to match, without leading dots.
command	string	Shell command to run
async	bool	Start the hook in the background instead of blocking the tool call

Placeholders:

• {file} or {{file}} — replaced with the saved file path

Environment variables:

• COSINE_ON_SAVE_FILE — Path to saved file
• COSINE_ON_SAVE_CONFIG — Path to config file
• COSINE_ON_SAVE_TOOL — Tool name that triggered the hook

[hooks]

[[hooks.on_save]]
matcher = "edit"
directories = ["apps/website"]
extensions = ["ts", "tsx"]
command = "pnpm exec eslint --fix --no-warn-ignored \"$COSINE_ON_SAVE_FILE\""
async = false

For scoped examples and execution details, see Hooks.

[projects] — Project Mappings

Map local directories to Cosine project IDs:

[projects]
"/Users/me/work/api" = { project_id = "proj_abc123" }
"/Users/me/work/web" = { project_id = "proj_def456" }

Command-line Overrides

TOML config is the long-lived source of truth, but you can override it per session with CLI flags.

Common examples:

cos start --model gpt-5.5 --reasoning high
cos start --profile work --debug
cos start --cdp-url http://localhost:9222 --auto-accept

For the full flag reference, examples, and in-page jump links, see Commands.

Environment Variables

COSINE_CONFIG_FILE

Override the default config file location:

export COSINE_CONFIG_FILE=/path/to/custom/config.toml
cos start

MCP Server Keys

Some MCP servers need API keys as environment variables:

export OPENAI_API_KEY=sk-...
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_...
cos start

Configuration Tips

1. Keep Secrets Private

Personal settings and auth tokens live in platform-specific Cosine config/home files. Keep them private. Deprecated repository automation settings go in cosine.toml or .cosine.toml and are safe to commit when they contain no secrets.

2. Use Profiles

cos --profile work start    # Work settings
cos --profile personal start # Personal settings

3. Temporary Overrides

cos start --model gpt-5.5 --debug  # One session only

4. Monorepo Setup

Mark root config to stop parent directory searches:

is_topmost_config = true

5. Validate Configuration

cos start --debug  # See loaded config
cos start          # Check MCP status in TUI

Next Steps

• MCP Configuration - Connect external tools (Slack, GitHub, Linear)
• Browser Automation - Configure Chrome CDP
• Skills - Manage reusable skill packages
• Overview - Full command reference