Configuration

Cosine CLI can be configured through three methods:

Command-line flags — Per-session overrides
TOML configuration files — User and project settings
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. Standalone inference credentials are also stored separately; see Standalone inference.

[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
agent_browser_enabled = false
agent_desktop_enabled = false

[computer.browser]
cdp_url = "http://localhost:9222"
launch_mode = "auto"

Repository automation config (`.cosine.toml` or `cosine.toml`)

This deprecated repository config is retained only for current project automation compatibility. It supports hooks, LSP, extra context, and project skills/initialization. It does not configure profiles, authentication, inference, or models. It is safe to commit to version control when it contains no secrets.

is_topmost_config = true

[agent]
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

Runtime flags have highest priority. Saved values in the selected personal profile come next, followed by build/code defaults. In particular, model selection is runtime override, then the profile’s model, then the build/code default; repository config no longer sets the model.

Some environment variables are selectors or runtime overrides rather than defaults. COSINE_CONFIG_FILE selects a different personal config file, and COSINE_AUTH_* variables override fields loaded from the platform-specific auth file.

Configuration Files

File	Location	Purpose
`config.toml`	Cosine config/home directory	Default personal profile
`config.<profile>.toml`	Cosine config/home directory	Named personal profile
`cosine.toml` or `.cosine.toml`	Repository root	Deprecated project automation compatibility
`mcp.json`	Cosine config/home directory	MCP servers
`inference.json`	Cosine config/home directory	Default-profile standalone inference credential
`inference.<profile>.json`	Cosine config/home directory	Named-profile standalone inference credential

Profiles

The Cosine config/home directory is platform-specific (typically ~/.cosine on macOS and Linux). Create different personal configurations for work and personal use:

# Use the default profile (config.toml)
cos

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

Named repository profiles such as cosine.work.toml are unsupported. An explicitly selected profile must exist. If it is missing, the CLI exits with its expected path, available named profiles, cos --profile work configure remediation, and the command for returning to the default profile.

cos configure selects its target profile before asking configuration questions. Selection precedence is an explicit --profile flag, then the target profile value, then the product default.

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:

Type / in an empty chat input to open the commands menu.
Search for autocomplete or select Autocomplete.
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. Deprecated repository config supports [agent].extra_context for project automation compatibility, but does not set the model.

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

Keep user config private — ~/.cosine/config.toml stores personal preferences, while auth tokens live in ~/.cosine/auth.json
Use profiles — Separate work and personal settings
Use is_topmost_config — In monorepo roots to stop parent config searches
Override with flags — For temporary changes without editing files

Detailed Reference

Flags — Complete global flag reference
Standalone inference — Configure a persistent OpenAI-compatible endpoint
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)