cosh-ng configuration

Start with the defaults. Use /auth, /mode, and /config language for interactive changes; edit TOML when settings must persist or be shared.

Files and authority

File	Read by	Scope
/etc/copilot-shell/config.toml	cosh-core and audit	Administrator defaults
~/.copilot-shell/config.toml	cosh-core and cosh-shell	User settings
<workspace>/.copilot-shell/config.toml	cosh-core	Project runtime preferences

Core layers files in system → user → project order. Project config may set Agent, Skill, session, active_model, and output-language preferences, but active_provider, provider definitions, MCP servers, Hook definitions, agent.approval_mode, agent.allowed_tools, and project audit settings are ignored. cosh-shell reads the user file, not the system or project file.

Minimal user configuration

[ai]
active_provider = "dashscope"
active_model = "qwen3.7-plus"
output_language = "en"

[ai.providers.dashscope]
type = "dashscope"
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
api_key = "${DASHSCOPE_API_KEY}"
model = "qwen3.7-plus"

[agent]
approval_mode = "recommend"
max_turns = 50
max_tool_calls_per_turn = 10

[skills]
custom_paths = ["~/team-skills"]

[session]
auto_persist = true
persist_dir = "~/.copilot-shell/cosh-core/sessions"

[logging]
level = "info"

[ui]
language = "auto"

[shell]
default = "auto"
integration = "enhanced"
login_identity = true
adapter_default = "cosh-core"
analysis_mode = "smart"
approval_mode = "auto"
status_symbols = false

Use environment expansion or /auth instead of writing a raw secret into TOML. See Providers for provider choices.

Approval and turn budgets

Core approval modes apply to direct integrations:

Mode	ReadOnly	FileEdit	Shell, network, MCP, external
trust	Run	Run	Run
auto	Run	Run	Ask
recommend	Run	Ask	Ask

Core and the shell use the same canonical names: recommend, auto, and trust. Existing balanced, suggest, and strict values are read as recommend; invalid configuration values also fall back to recommend. agent.max_turns limits one Agent request (default 50), while max_tool_calls_per_turn defaults to 10. A new prompt starts a fresh turn budget.

Sessions and compaction

[session]
auto_persist = true
persist_dir = "~/.copilot-shell/cosh-core/sessions"

[session.compaction]
enabled = true
auto = true
trigger_ratio = 0.70
emergency_ratio = 0.90
target_ratio = 0.30
preserve_recent_runs = 2
# auto_compact_token_limit = 89600
# model_context_window = 128000
# model_max_output_tokens = 8192

Keep target_ratio <= trigger_ratio <= emergency_ratio. Compaction changes only the model-visible history; the persisted transcript remains complete. Set auto_persist = false to disable resumability for the process.

MCP and other optional sections

Define MCP clients only in system or user config. Each server uses one of command (stdio) or url (Streamable HTTP); allowed_tools omitted means all, while [] means none. Follow Connect an MCP server for examples, OAuth, and lifecycle commands.

For shell recommendations and health checks, add only what you need:

[shell.recommendations]
enabled = true
bash_history = false

[health]
enabled = true
role = "web-server"
critical_mounts = ["/", "/var"]

[[health.services]]
name = "nginx"
expected = "active"

integration accepts native or enhanced. Enhanced is the default and starts in Assisted mode, with marker-based Agent routing and command events. At an empty prompt, Shift+Tab switches between Assisted and Shell-only; Shell-only keeps command events and post-command insights but sends ordinary input to bash or zsh. Native leaves input, Shell options, traps, and startup files under bash or zsh ownership and provides no Cosh observation or insights. The integration value is read when cosh starts, so changing it requires a new session. Invalid values reject startup with a visible error.

status_symbols is false by default. Set it to true (or COSH_SHELL_STATUS_SYMBOLS=1 for one session) to show a ◇ (Assisted) or ◌ (Shell-only) status line above each Enhanced prompt. Native sessions never show status symbols. The value is read at startup, and invalid values fall back to false.

analysis_mode accepts smart, auto, or manual; shell approval accepts recommend, auto, or trust. health.services.expected accepts active or inactive.

login_identity (default true) gives an interactive Enhanced login shell a real login identity: the inner bash starts as a login shell (shopt -q login_shell == yes) and reads /etc/profile and ~/.bash_profile like bash -l. Set login_identity = false to fall back to the previous non-login startup (--rcfile). Bash 4 and newer use the login-identity path when the bounded real-launch capability probe succeeds. Bash 3.2 (including the macOS system Bash), probe failures, and parent environments that export function names POSIX startup cannot import all fall back automatically. The fallback marker still reads the login profile exactly once.

For an Enhanced Bash login, Cosh captures the final startup PATH once after the login profile and the first user PROMPT_COMMAND hook, but before the first Cosh prompt boundary. Only provider child processes inherit this value; Cosh does not change its process-wide PATH. A missing, malformed, oversized, forged, or late report leaves providers on the inherited PATH. Set COSH_SHELL_BOOTSTRAP_PATH=0 to disable both legacy PATH probes and this Bash startup PATH handoff. Zsh and Bash non-login probe behavior is otherwise unchanged.

Login upgrade notice

At login, cosh-shell checks for an available managed cosh-ng update in the background and shows a notice when it finds one. The check is enabled by default. Set COSH_SHELL_UPGRADE_CHECK to off, 0, false, or no (case-insensitive) to disable it for the next session. Set COSH_SHELL_UPGRADE_CHECK_CACHE to override the cache file path; the default is ~/.copilot-shell/cosh/upgrade-check.json.

When cosh-ng was installed by anolisa in system scope with the default raw backend, the notice appears only for root sessions. A regular user cannot run the system-scope update check because it needs write access to /var/cache/anolisa, so the notice stays hidden. To check manually, run sudo anolisa --install-mode system update cosh-ng --dry-run. RPM-backend installations are not affected.

Logging

[logging].level sets the log filter for both cosh-shell and cosh-core (default info). The resolution order is:

1. COSH_LOG environment variable
2. RUST_LOG environment variable
3. [logging].level

[ui].log_level is still accepted as a legacy alias for existing configs; [logging].level wins when both are set. [ui].debug = true raises the effective level to debug while the level is still the default info.

The value is a tracing EnvFilter expression, so per-module control works: COSH_LOG=cosh_core=debug turns on cosh-core debug records only.

Logs are written to ~/.copilot-shell/logs/ as cosh-shell.log.<date> and cosh-core.log.<date>. If the directory is not writable, records go to stderr instead. Retention keeps today plus the previous two UTC dates within a per-user budget of 20 MiB shared by both components; when the budget is exhausted, the process stops writing log records (announced on stderr) until older files are removed and the session restarts.

Audit settings

Audit settings come from the system file when it has an [audit] table; otherwise the user table is used. Project audit tables are ignored.

[audit]
mode = "best_effort"         # best_effort | required
retention_days = 30
max_disk_bytes = 1073741824

retention_days and max_disk_bytes must be greater than zero. The storage root is $XDG_STATE_HOME/cosh/audit or ~/.local/state/cosh/audit; set COSH_AUDIT_DIR to an absolute path to override it.

Telemetry opt-out

cosh-ng collects anonymous operational metrics to improve service quality. This includes tool call counts, token usage, approval statistics, OS type/architecture, and a persistent installation UUID for cross-session correlation. No user prompts, code content, or conversation content is collected.

Telemetry is enabled by default. To disable it for the current user, create the per-user sentinel file:

mkdir -p ~/.copilot-shell
touch ~/.copilot-shell/telemetry_disabled

A system administrator can disable telemetry for all users on the machine by creating the system-level sentinel file:

sudo mkdir -p /etc/anolisa
sudo touch /etc/anolisa/.telemetry_disabled

Either sentinel takes effect immediately for running processes; no restart is required.

Environment overrides

Variables	Effect
COSH_AI_PROVIDER, COSH_MODEL, COSH_OUTPUT_LANGUAGE	Core provider, model, and response language
COSH_APPROVAL_MODE, COSH_MAX_TURNS	Core approval and per-request turn budget
DASHSCOPE_API_KEY, OPENAI_API_KEY, OPENAI_BASE_URL	OpenAI-compatible credentials and URL fallbacks
ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET, ALIBABA_CLOUD_SECURITY_TOKEN	Aliyun credential fallbacks
COSH_SHELL_DEFAULT_SHELL, COSH_SHELL_ADAPTER, COSH_SHELL_ANALYSIS_MODE, COSH_SHELL_APPROVAL_MODE	Interactive shell choices
COSH_SHELL_INTEGRATION	native or enhanced Shell integration for the next session
COSH_SHELL_LOGIN_IDENTITY	on/off real login identity for the next Enhanced login shell (default on)
COSH_SHELL_BOOTSTRAP_PATH	Set to 0 to disable startup PATH discovery and the Bash login PATH handoff
COSH_SHELL_LANG, COSH_SHELL_AI, COSH_SHELL_INPUT_WAIT_TIMEOUT_SECS	Shell language, AI toggle, and input-wait timeout
COSH_SHELL_UPGRADE_CHECK	Login upgrade notice check; enabled by default, set off, 0, false, or no to disable
COSH_SHELL_UPGRADE_CHECK_CACHE	Override the login upgrade notice cache path (default ~/.copilot-shell/cosh/upgrade-check.json)
COSH_RECOMMENDATIONS_BASH_HISTORY	Opt in to Bash-history recommendations
COSH_LOG, RUST_LOG	Log filtering (COSH_LOG wins)
COSH_AUDIT_DIR	Audit storage root

Environment values take precedence when the relevant binary supports them. Logs rotate daily under ~/.copilot-shell/logs/; see Logging for retention.