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

Project-specific settings. Safe to commit to version control.

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

[agent]
model = "gpt-5.3-codex"
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

Configuration is usually resolved in this order (highest to lowest priority):

1. Command-line flags - Override everything else
2. Repository config - Project-specific settings in cosine.toml
3. User config - Personal settings in ~/.cosine/config.toml
4. Environment variables - Auth and file-location overrides
5. Default values - Built-in defaults

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
~/.cosine/config.toml	User settings and preferences	User-wide
.cosine.toml or cosine.toml	Project-specific settings	Repository
cosine.<profile>.toml	Profile-specific project config	Repository
~/.cosine/config.<profile>.toml	Profile-specific user config	User-wide
~/.cosine/mcp.json	MCP server definitions	User-wide

Profile-Specific Configs

Create multiple profiles for different contexts:

# Use work profile (looks for cosine.work.toml or ~/.cosine/config.work.toml)
cos --profile work start

# Use personal profile
cos --profile personal start

Profile resolution order:

1. cosine.<profile>.toml in repo (project-specific)
2. ~/.cosine/config.<profile>.toml in Cosine home (user-specific)

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
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
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

[browser] — Browser Automation

Field	Type	Description
cdp_url	string	Chrome DevTools URL, e.g., http://localhost:9222
tool_backend	string	Browser tool backend: browser, browseruse, or safari on supported macOS surfaces

[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] — Project Defaults

In .cosine.toml or cosine.toml, [agent] controls project-specific defaults.

Field	Type	Description
model	string	Model override for this repo
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

User settings go in ~/.cosine/config.toml and auth tokens live in ~/.cosine/auth.json. Keep both private. Project settings go in cosine.toml or .cosine.toml and are safe to commit when they contain only project defaults.

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