Configuration

Cosine CLI can be configured through three methods (in priority order):

1. Command-line flags — Override everything (highest priority)
2. TOML configuration files — User and project settings
3. Environment variables — System-level overrides

---

Quick Start

User Config (~/.cosine.toml)

Your personal settings and API tokens. Never commit this file.

[auth]
user_id = "usr_xxx"
token = "tok_xxx"

[inference]
model = "gpt-5"
reasoning_level = "medium"

[config]
system_prompt_id = "lumen"
shell = "/bin/zsh"
agent_commits = true

[browser]
cdp_url = "http://localhost:9222"

Project Config (cosine.toml)

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

is_topmost_config = true

[agent]
model = "codex"
extra_context = "AGENTS.md"

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

Common Flags

# Override model for one session
cos start --model gpt-4o --reasoning high

# One-shot automation
cos start --prompt "Review code" --auto-accept

# Use profile
cos start --profile work

# Debug mode
cos start --debug

---

Configuration Priority

Priority	Source	Use Case
1	Command flags	Temporary overrides
2	cosine.toml	Project settings
3	~/.cosine.toml	Personal preferences
4	Environment vars	System defaults
5	Built-in defaults	Fallbacks

---

Configuration Files

File	Location	Purpose
~/.cosine.toml	Home directory	User settings, secrets
cosine.toml	Repository root	Project settings
~/.cosine.<profile>.toml	Home directory	Profile configs
cosine.<profile>.toml	Repository	Profile configs
~/.cosine/mcp.json	Home directory	MCP servers

Profiles

Create different configurations for work/personal:

# Use work profile
cos --profile work start

# Use personal profile
cos --profile personal start

---

Essential Sections

[inference] — LLM Settings

Option	Default	Description
model	gpt-5.4	Main agent model
small_model	claude-sonnet-4-6-1m	Fast tasks
micro_model	claude-haiku-4-5	Memory queries
reasoning_level	medium	none, low, medium, high, xhigh, adaptive (model-dependent)
max_context_tokens	0	Context limit (0=unlimited)
max_turns	0	Turn limit (0=unlimited)

[config] — General Settings

Option	Default	Description
system_prompt_id	lumen	lumen, judge, orchestrator
agent_commits	true	Auto-create Agent Commits after each turn
shell	$SHELL	Terminal shell
theme	dark	dark or light
ultra_enabled	false	Background daemon

[agent] — Tool Settings

[agent]
# Disable specific tools
disabled_tools = ["edit", "mcp_slack_*"]

---

Environment Variables

# Override config file location
export COSINE_CONFIG_FILE=/path/to/config.toml

# MCP server API keys
export OPENAI_API_KEY=sk-...
export GITHUB_TOKEN=ghp_...

---

Best Practices

1. Keep secrets in ~/.cosine.toml — Never commit API tokens
2. Use profiles — Separate work and personal settings
3. Use is_topmost_config — In monorepo roots to stop parent config searches
4. Override with flags — For temporary changes without editing files

---

Detailed Reference

• Flags — Complete global flag reference
• TOML Configuration — Complete TOML file reference
• Reasoning — How reasoning levels change model behavior
• Commands — Command overview and examples
• MCP Configuration — Connect external tools (Slack, GitHub, Linear)