Frequently asked questions

cosh is a general-purpose coding agent for the terminal, written entirely in Rust. It pairs software engineering tools (file editing, search, shell, LSP, web) with computer tools that let it observe and drive graphical applications through the OS accessibility tree. The TUI is built from scratch with Ratatui — providers, models and modes are configured right in the interface, with almost zero manual setup.

One command: curl -fsSL https://raw.githubusercontent.com/DiegoZaluski/co-sh/main/download.sh | bash on Linux and macOS (also works on Windows via Git Bash or WSL), or irm https://raw.githubusercontent.com/DiegoZaluski/co-sh/main/download.ps1 | iex on Windows PowerShell. You get a single compiled binary with no runtime dependencies. Optional environment variables: COSH_BIN_DIR (install directory), COSH_VERSION (specific version) and COSH_VARIANT (variant selection — see the questions below). Note: curl | bash does not work in PowerShell or CMD — use the PowerShell script there.

Same one-command install — set COSH_VARIANT before running it: COSH_VARIANT=slim-embed curl -fsSL https://raw.githubusercontent.com/DiegoZaluski/co-sh/main/download.sh | bash on Linux and macOS, or in PowerShell: $env:COSH_VARIANT = "slim-embed"; irm https://raw.githubusercontent.com/DiegoZaluski/co-sh/main/download.ps1 | iex. Prebuilt slim-embed binaries are published for Linux x64 and Windows x64 — macOS releases ship the slim variant only, so macOS users get the default build regardless of this variable.

slim is the default build of cosh. slim-embed is the same binary with the embed feature compiled in, which adds the recall module and its recall_search tool — semantic vector search over knowledge bases stored locally in LanceDB. Embeddings are computed locally (fastembed via ONNX Runtime, CPU-only; models download automatically on first use), so indexing and searching your knowledge base happens on your machine. Everything else — tools, agent modes, providers — is identical in both variants.

Linux and Windows are tested. macOS builds are published but haven't been tested yet — if anything fails there, open an issue with as much detail as possible. Prebuilt binaries are available for x64 and arm64.

cosh ships native adapters for Claude, OpenAI and Gemini, plus an OpenAI-compatible connector family that covers Amazon Bedrock, Kimi (Moonshot AI), Groq, OpenRouter, Nvidia and more. Local model servers like Ollama can be added with /providers, and custom LLM providers or ACP agents can be registered in Settings → Integrations. Everything is picked from inside the TUI with /models — no config file editing required.

Not in setup.json. API keys are obtained from the OS keyring and/or provider-specific environment variables. Some providers (GitHub Copilot, Charm) support OAuth 2.0 device sign-in directly from the interface. If a message fails for missing or broken credentials, cosh offers its free gateway with OAuth sign-in once, right in the session.

cosh has four agent modes, cycled with Tab in the session: build (the default — the agent works, but shell commands need your approval), ask (read-only — the agent answers and plans, and can't run shell commands), yolo (no approval prompts — the agent runs commands without asking) and command. On top of the modes, all paths are sandboxed: nothing is accessible until the project root is set, with write and read-only allow/blocklists.

cosh itself is free and open source under the Apache-2.0 license. You pay only your model provider's API usage — the session tracks token counts and cost as you go. If you don't have a provider configured, cosh points you to a free third-party gateway with OAuth sign-in so you can try it without an API key. Note that free providers are third-party services that cosh merely recommends — they are not part of, operated by, or affiliated with cosh, and their terms, limits and availability are up to them.

No conversations, code or credentials are ever sent. Telemetry is limited to aggregated product metrics — session duration, token counts, provider/tool usage categories, error kinds — and is documented in detail in the telemetry docs. You can disable it in /settings → General. The only free-text field in the schema is optional uninstall feedback.

cosh can observe and drive native desktop applications through the OS accessibility tree (X11 and Wayland), with screenshots as a fallback. It reads a structured, compact representation of the interface instead of processing images, so fewer tokens are consumed — and it can perform window verbs too: activate, minimize, maximize, move, resize and close.

The /agents split runs external agents (Gemini, Claude, Codex, Cline, and other ACP harnesses) alongside the main agent, one pane each, all sharing a single prompt. Every pane keeps its own session, model and optional git worktree — panes never coordinate themselves: the main agent dispatches tasks and collects reports as one team. Worktree isolation is opt-in per pane.

When a newer release is detected, the session footer shows a current → new version hint — click it and cosh updates in place using the same install pipeline. You can also re-run the install one-liner at any time, or pin a specific version with COSH_VERSION. Releases are listed on GitHub Releases.

Open an issue on GitHub with as much detail as possible — bugs, platform quirks (especially macOS) and feature suggestions are all welcome. The project is Apache-2.0, and its building blocks are published as reusable crates — cosh-sdk, cosh-tools, cosh-tui and cosh-recall — so you can build agents on top of cosh.