Configuration

Cosine CLI can be configured through three methods:

1. Command-line flags — Per-session overrides
2. TOML configuration files — User and project settings
3. Environment variables — Auth and file-location overrides

---

Quick Start

User Config (~/.cosine/config.toml)

Your personal settings. Never commit this file.

Authentication tokens are stored separately in ~/.cosine/auth.json (managed automatically by cos login / cos logout) and never appear in config.toml.

[inference]
model = "gpt-5.5"
model_selection_id = "cosine:gpt-5.5"

[config]
system_prompt_id = "lumen"
reasoning_level = "medium"
shell = "/bin/zsh"
agent_commits = true
ghost_text_enabled = 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 = "gpt-5.3-codex"
extra_context = "AGENTS.md"

[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

Common Flags

# Override model for one session
cos start --model gpt-5.5 --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/config.toml	Personal preferences
4	Environment vars	Auth and config-file overrides
5	Built-in defaults	Fallbacks

Some environment variables are not simple defaults. COSINE_CONFIG_FILE selects a different user config file, and COSINE_AUTH_* variables override fields loaded from ~/.cosine/auth.json.

---

Configuration Files

File	Location	Purpose
~/.cosine/config.toml	Cosine home	User settings and preferences
cosine.toml	Repository root	Project settings
.cosine.toml	Repository root	Project settings, preferred when both files exist
~/.cosine/config.<profile>.toml	Cosine home	User 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
base_url	https://api.cosine.sh	OpenAI-compatible inference endpoint
model	lumen-outpost	Main agent model
model_selection_id	derived from model	Provider-qualified model ID, such as cosine:gpt-5.5
small_model	claude-sonnet-4-6-1m	Fast tasks
micro_model	claude-haiku-4-5	Memory queries
review_model	gemini-3.1-pro	Code review tasks
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
reasoning_level	medium	none, low, medium, high, xhigh, adaptive, or max
mode	manual	Startup mode: manual, auto, plan, swarm
agent_commits	true	Auto-create Agent Commits after each turn
api_sessions	true	Use API-backed session persistence and resume
ghost_text_enabled	true	Enable inline autocomplete suggestions in the TUI
shell	$SHELL	Terminal shell
theme	dark	dark or light
ultra_enabled	false	Background daemon

Autocomplete suggestions

Autocomplete shows inline suggestions while you type in the TUI. It is enabled by default.

To toggle it from the TUI:

1. Type / in an empty chat input to open the commands menu.
2. Search for autocomplete or select Autocomplete.
3. Press Enter.

You can also run /autocomplete directly. The preference is saved to your CLI config as ghost_text_enabled.

When autocomplete is off, Cosine does not request background autocomplete suggestions.

User [agent] — Tool Settings

[agent]
# Disable specific tools
disabled_tools = ["edit"]

In user config, [agent] supports disabled_tools. Repository config has its own [agent] section for project-specific model and extra_context.

---

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 user config private — ~/.cosine/config.toml stores personal preferences, while auth tokens live in ~/.cosine/auth.json
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)