Setup reference

This is the complete reference for Cosh’s setup.json. It is intentionally short: use the TUI first, and edit the file directly only when you need a precise or advanced configuration.

Start in the TUI

The distributed slim Cosh starts directly in a session. It has no Home screen. Type these commands in the chat input and press Enter:

Changes made in the TUI are saved to setup.json. Navigate with the arrow keys, press Enter to edit, and Esc to go back.

Where the file lives

On Unix, the default path is ~/.config/cosh/setup.json. On other platforms, Cosh uses the operating system’s application configuration directory. Set COSH_CONFIG_DIR to use another directory; Cosh then reads and writes <that-directory>/setup.json.

The file is JSON. Missing fields use their defaults. A missing or invalid file also starts with defaults. COSH_DATA_DIR changes the data directory for sessions and caches; it does not change the location of setup.json.

Quick map

appearance

The TUI commands /background, /bell, and /anim edit the corresponding boolean fields.

tools

routing

All chains are ordered: Cosh tries the first entry, then the next one.

When fallbacks is empty or missing, the built-in order is:

1. nvidia → deepseek-ai/deepseek-v4-pro
2. openrouter → deepseek/deepseek-v4-pro
3. groq → openai/gpt-oss-120b
4. charm → deepseek-ai/deepseek-v4-pro

A model fallback entry is:

{ "provider": "openrouter", "model": "deepseek/deepseek-v4-pro" }

Prompt-corrector entries are tagged objects:

[
  { "kind": "model", "provider": "openrouter", "model": "..." },
  { "kind": "acp", "agent": "my-agent" }
]

hooks

Use /settings → Automation → PreToolUse hooks or PostToolUse hooks. The detailed lifecycle and exit-code behavior is documented in hooks.md.

Each event array contains objects with:

Example:

{
  "hooks": {
    "pre_tool_use_enabled": true,
    "post_tool_use_enabled": true,
    "PreToolUse": [
      { "name": "protect files", "matcher": "^write_file$", "command": "./check-write.sh", "timeout": 10 }
    ],
    "PostToolUse": []
  }
}

providers

providers.local maps a local provider name to its endpoint. Add it with /providers → ADD Provider.

{
  "providers": {
    "local": {
      "ollama": { "base_url": "http://localhost:11434" }
    }
  }
}

API keys for regular providers are not setup.json settings: Cosh obtains them from the OS keyring and/or provider-specific environment variables.

model and mode

These sections persist the last choice for new sessions; they do not rewrite existing session history.

Use /models for model.*. Cycle the agent mode with the session’s mode shortcut (Tab); the selected mode is saved automatically.

cache

Configure these in /settings → Models & caching. The input accepts blank, minutes, 45m, 1h, or 1h30m, up to 24 hours. The stored values are wishes in minutes; Cosh maps them to the API values that each provider supports.

skills

Configure the source list in /settings → Environment → Skill directories. Enter multiple directories separated by :. An empty list uses ~/.skills. Each source contains one directory per skill, with a SKILL.md inside; the first source wins when names collide. A path beginning with ~ is expanded.

recursive, ignore, and include currently have no TUI control; edit them directly in setup.json when needed.

model_decision (ONNX builds only)

The distributed slim binary has no Home screen and is built without the ONNX feature, so these settings are not shown in its TUI and no local decision model runs there. They remain part of the file schema for binaries built with --features onnx. In those builds, use /settings → Automation.

The named model kinds are selected by Checkup model. A custom checkpoint is file-only:

{
  "model_decision": {
    "model": { "kind": "custom", "repo": "/path/to/checkpoint", "subfolder": null }
  }
}

COSH_ONNX_HUB_REPO overrides model_decision.hub.repo. The legacy top-level name checkup is still accepted when reading, but Cosh writes model_decision.

lsp, mcp, editor, and telemetry

mcp

Manage servers in /settings → Integrations → MCP servers. A server is enabled by default; disabling it skips it at startup.

{
  "mcp": {
    "servers": [
      {
        "name": "local-tools",
        "enabled": true,
        "transport": {
          "type": "stdio",
          "command": "my-mcp-server",
          "args": ["--stdio"],
          "env": {},
          "cwd": null
        }
      },
      {
        "name": "remote-tools",
        "transport": {
          "type": "http",
          "url": "https://example.com/mcp",
          "headers": {},
          "api_key_env": "MCP_API_KEY",
          "timeout_ms": 30000
        },
        "enabled": true
      }
    ]
  }
}

In the TUI, enter a command and arguments for stdio, or an http(s):// URL for HTTP. Timeout is entered in seconds; the file stores milliseconds and defaults to 30000 (30 seconds). HTTP credentials entered as a literal key are stored in the OS keyring, not in setup.json; entering $VAR stores the environment-variable name in api_key_env. Stdio credentials belong in that server’s transport.env.

Environment values that affect setup

These are convenience inputs, not additional JSON fields:

For normal use, configure through the TUI and let Cosh write the file. Edit setup.json directly for skills filters, custom decision checkpoints, advanced routing, or automation that must be reproducible.