TOML Config

Cosine CLI can be configured through multiple sources: TOML configuration files, command-line flags, and environment variables. This guide covers all configuration options with complete examples.

Quick Navigation

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

Example Configs

User config

Your personal settings, API tokens, and global preferences. Keep this file private — it contains secrets!

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

# ------------------------------------------------------------
# AUTHENTICATION (Auto-populated via `cos login`)
# ------------------------------------------------------------
[auth]
user_id = "usr_123456789"
token = "tok_abcdef123456"
team_id = "team_abc123"
team_name = "My Organization"
team_slug = "my-org"

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

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

[inference]
base_url = "https://api.cosine.wtf"
model = "gpt-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"
shell = "/bin/zsh"
agent_commits = true
memory_recall_mode = "every"
memory_recall_detail = "snippet"
theme = "dark"

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

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

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

# ------------------------------------------------------------
# TOOL CONFIGURATION
# ------------------------------------------------------------
[agent]
disabled_tools = ["edit", "mcp_slack_*"]

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 = "codex"
extra_context = "AGENTS.md"

[hooks]
on_save = "npm run lint -- --fix {file}"

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 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.toml
4. Environment variables - System-level overrides
5. Default values - Built-in defaults

Configuration File Locations

File	Purpose	Scope
~/.cosine.toml	User settings, auth tokens, global preferences	User-wide
cosine.toml or .cosine.toml	Project-specific settings	Repository
cosine.<profile>.toml	Profile-specific project config	Repository
~/.cosine.<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.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.<profile>.toml in home (user-specific)

Configuration Sections Reference

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

[auth] — Authentication

Populated automatically via cos login. Manual configuration is rarely needed.

Field	Type	Description
user_id	string	Your Cosine user ID
token	string	API authentication token
team_id	string	Your team ID
team_name	string	Your team name
team_slug	string	Your team slug
auth.openai.auth_method	string	"cosine" or "oauth"
auth.openai.oauth_redirect_uri	string	OAuth callback URL

[api] — Cosine API

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

[inference] — LLM Settings

Field	Type	Default	Description
base_url	string	https://api.cosine.wtf	OpenAI-compatible endpoint
model	string	gpt-5.4	Default agent model
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 (unlimited)	Max context window
max_turns	int	0 (unlimited)	Max conversation turns

Available models: gpt-5, codex, lumen, claude-sonnet, gemini-3.1-pro, etc.

[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
shell	string	$SHELL	Preferred shell for terminal
agent_commits	bool	true	Auto-create Agent Commits per turn
memory_recall_mode	string	every	every or first (when to recall)
memory_recall_detail	string	snippet	snippet or full (memory detail)
theme	string	dark	UI theme: dark or light
ultra_enabled	bool	false	Enable Ultra daemon

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

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.

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

[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 messages
linear = 0     # Linear issues
gmail = 5      # Gmail

[agent] — Tool Configuration

Field	Type	Description
model	string	Model override for this repo
extra_context	string	Path to context file (e.g., AGENTS.md)
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

[hooks] — Automation

Field	Type	Description
on_save	string	Command to run after file writes

Placeholders:

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

Environment variables:

• COSINE_ON_SAVE_FILE — Path to saved file
• COSINE_ON_SAVE_CONFIG — Path to config file

[hooks]
on_save = "go test ./... -run TestRelatedTo{file}"

[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 --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_...
export SLACK_BOT_TOKEN=xoxb-...
cos start

Configuration Tips

1. Keep Secrets Private

API tokens go in ~/.cosine.toml (never commit). Project settings go in cosine.toml (safe to commit).

2. Use Profiles

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

3. Temporary Overrides

cos start --model codex --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