# Agent compatibility

What kosa8 does for each AI coding agent and MCP client. The same table is printed by `kosa8 agent compat`, shown in the desktop app under Agents & skills, and in the kosa8 Cloud dashboard, all generated from the code that does the work.

## What each column means

- **Sandbox**: a built-in kit runs the agent in a kosa8 microVM with `kosa8 agent run KIT` (or headless with `kosa8 prompt -a KIT`). It sees one folder, and reaches only the hosts the kit allows. The agent's CLI is installed from npm, pinned to one version and its tarball digest.

- **Key brokered**: the agent's API key stays on your computer, in the sandbox's egress broker. The sandbox holds a placeholder that only works through that broker ([Keep API keys out](https://docs.kosa8.com/guides/credentials/)).

- **Checked calls**: before each tool call runs, the agent's own hook asks the broker, and the [kosa8 rules](https://docs.kosa8.com/guides/tool-rules/) allow it, flag it, hold it for you, or refuse it.

- **kosa8 skill**: `kosa8 skill install AGENT` teaches the agent when to use a sandbox.

- **MCP**: `kosa8 mcp install CLIENT` gives the agent kosa8's sandbox tools.

## The matrix

| Agent or client | Sandbox (kit) | Key brokered | Checked calls | kosa8 skill | MCP |
|---|---|---|---|---|---|
| Claude Code | `claude` | yes | yes: PreToolUse hook in managed settings | `~/.claude/skills` | `claude mcp add` |
| OpenAI Codex CLI | `codex` | yes | yes: PreToolUse hook in `/etc/codex/requirements.toml`, managed hooks only | `~/.agents/skills` | `~/.codex/config.toml` |
| Gemini CLI | `gemini` | yes | yes: BeforeTool hook in `/etc/gemini-cli/settings.json` | `~/.gemini/skills` | `~/.gemini/settings.json` |
| Qwen Code | `qwen` | yes (OpenAI-compatible) | yes: PreToolUse hook in `/etc/qwen-code/settings.json` | `~/.qwen/skills` | `~/.qwen/settings.json` |
| OpenCode | `opencode` | yes | yes: a `tool.execute.before` plugin | `~/.config/opencode/skills` | `~/.config/opencode/opencode.json` |
| Crush (Charm) | `crush` | yes | yes: PreToolUse hook in the global `crushrc` | `~/.config/crush/skills` | by hand |
| GitHub Copilot (CLI and VS Code) | `copilot` | no | no | `~/.copilot/skills` | `~/.copilot/mcp-config.json` |
| VS Code workspace | – | – | – | – | `.vscode/mcp.json` (`--project`) |
| Cursor | refused as shipped | – | – | `.cursor/rules/kosa8.mdc` | `~/.cursor/mcp.json` |
| Windsurf | – | – | – | `~/.agents/skills` | `~/.codeium/windsurf/mcp_config.json` |
| Cline | – | – | – | `~/.cline/skills` | `~/.cline/data/settings/cline_mcp_settings.json` |
| Amp | – | – | – | `~/.config/amp/skills` | `~/.config/amp/settings.json` |
| Goose | – | – | – | `~/.agents/skills` | `~/.config/goose/config.yaml` |
| Kilo Code | – | – | – | `~/.kilo/skills` | `~/.config/kilo/kilo.json` |
| Factory Droid | – | – | – | `~/.factory/skills` | `~/.factory/mcp.json` |
| Continue | – | – | – | `.continue/rules/kosa8.md` | `.continue/mcpServers/kosa8.json` (`--project`) |
| Zed | – | – | – | – | `~/.config/zed/settings.json` (macOS, Linux) |
| Claude Desktop | – | – | – | – | `claude_desktop_config.json` |
| JetBrains AI Assistant | – | – | – | – | settings dialog; `kosa8 mcp install jetbrains` prints what to paste |

Agents without checked calls still get everything else in their row: an agent run in a kit is in the sandbox, its network is limited to the kit's hosts, and every model request through the broker is recorded. Checked calls add a decision before each call, not the boundary; the sandbox is the boundary.

## How checked calls fail

The hook kosa8 installs refuses the call whenever it cannot get an answer: no broker, an error, an answer it cannot read, or a broker slower than 25 seconds. A hook that let the call run on failure could be switched off by breaking it. Two things the hook cannot catch are left to the agent: if the agent kills the hook process or times it out, Codex, Gemini CLI, Qwen Code and Crush let the call run. kosa8 records each tool call the model asked for that was never checked (`sandbox.tool_call.unchecked`), so a skipped check shows up in the audit log.

The hook's settings go where each agent reads administrator settings, and the rules refuse a tool call that writes there (K8-D002). Codex and Claude Code are also told to run managed hooks only, so a project's settings cannot add one that answers first. Gemini CLI and Qwen Code have no such switch; Crush has no administrator level at all, so a project `.crushrc` could remove the hook, and the rules refuse writing one.

## Not covered, and why

- **Copilot CLI**: it cannot be pointed at another API host, so its token cannot be brokered and is passed in, and with no broker there is nothing for a hook to ask.

- **Cursor CLI**: Cursor publishes it only as an install script that cannot be pinned.

- **Aider and Goose**: not published on npm, which is what kits pin today.

- **Amp and Factory Droid**: both need their vendor's own service and key, which have no documented base URL to broker.

- **Cline CLI and Kilo Code CLI**: Cline has no build for Alpine and takes its key through `cline auth`; Kilo's provider base URL is not documented. Their skills and MCP setup work.

- **Crush MCP**: Crush now keeps MCP servers in `crushrc`; add kosa8 there by hand.

## Importing someone else's skill

An Agent Skill is a folder with a `SKILL.md` and often scripts the agent is told to run. That is code from a stranger, so `kosa8 skill add` reads all of it before any agent sees it.

```
$ kosa8 skill add github.com/OWNER/REPO/skills/pdf --dry-run
$ kosa8 skill add github.com/OWNER/REPO/skills/pdf@v1.2.0 -a claude-code -a codex
$ kosa8 skill ls
$ kosa8 agent run claude --skill pdf
$ kosa8 skill rm pdf
```

1. **Fetch.** A GitHub ref is resolved to a commit first, and the folder is read from that commit. Links, paths that climb out of the folder, and anything over 500 files or 16 MB are refused.

2. **Show.** Every file is listed, with scripts and binaries marked, the tools the skill asks to use without asking (`allowed-tools`) and the web hosts it names.

3. **Scan.** Every shell script and every shell block in its Markdown goes through the same rule pack an agent's own commands do. Binaries, hidden or direction-changing characters, HTML comments and credential paths are reported too. Code in other languages is listed for you to read; the rules do not read it.

4. **Refuse.** A finding at ask or deny stops the import unless you pass `--accept-findings`. `--digest sha256:…` refuses anything but the content you expect.

5. **Pin.** The skill is kept in `~/.kosa8/skills` under a SHA-256 of its content, and copied to each agent. `kosa8 skill ls` says if the stored copy or an installed copy has changed since.

6. **Run it sandboxed.** `kosa8 agent run KIT --skill NAME` mounts the pinned copy read-only in the sandbox and puts it where that agent reads skills, so its scripts run in there, not on your computer.

---
Source: https://docs.kosa8.com/guides/compatibility/