AI clients

The kit works in each AI client in four ways: skills, reviewer agents, an MCP server and a hook. Each way runs the same CLI, so the results are the same in every client.

Client	Skills	Agents	MCP	Hook for gh pr and gh issue
Claude Code	~/.claude/skills	~/.claude/agents	claude mcp add	~/.claude/settings.json, PreToolUse
Codex	~/.codex/skills	~/.codex/agents (TOML)	codex mcp add	~/.codex/hooks.json, PreToolUse
OpenCode	reads the Claude Code and Codex skills	~/.config/opencode/agents	opencode.json	—
Antigravity	~/.gemini/config/skills	—	~/.gemini/config/mcp_config.json	~/.gemini/config/hooks.json, PreToolUse on run_command
Cursor	~/.cursor/skills	~/.cursor/agents	~/.cursor/mcp.json	~/.cursor/hooks.json, beforeShellExecution
Gemini CLI (paths from docs, not tested)	~/.gemini/skills	—	~/.gemini/settings.json	—
Kilo (paths from docs, not tested)	reads the Claude Code and Codex skills	—	~/.config/kilo/kilo.jsonc	—
Hermes	~/.hermes/skills/desk	—	hermes mcp add	hermes config set hooks.pre_tool_call, on the terminal tool

Claude Code with more than one config folder. The kit installs into $CLAUDE_CONFIG_DIR, ~/.claude, and each ~/.claude-* folder that Claude Code has used (it has projects/, history.jsonl or .credentials.json). A skills or agents folder that two config folders share through a link gets one write.

Hermes. $HERMES_HOME sets the profile folder (default ~/.hermes). The kit changes config.yaml through the hermes CLI, so the comments in the file stay. Hermes runs a new shell hook only after the person approves it one time, at the next interactive start. hermes hooks list shows the approval status. The Hermes curator changes only agent-created skills, so it does not change the kit skills.

In a repository, desk install --scope repo writes .claude/skills and .agents/skills (read by every client above) and .claude/agents, .codex/agents and .opencode/agents (Cursor reads .claude/agents). Hermes reads .agents/skills after you run hermes skills trust in the repository.

Each client also gets the headless engine where it has one: desk review --engine claude|codex|opencode.

Install

See the README. Each install command installs into every client that it finds on PATH. --client claude,cursor names the clients; --no-hooks, --no-mcp and --no-agents leave parts out; --dry-run prints the plan. A client config file is backed up before each change (<file>.bak-<time>).

When to use which

• Skills are the normal way. Say what you want; the skill calls the CLI.
• Agents give each profile its own context. Ask for "review PR 12 with all relevant profiles": the main session starts one agent for each profile in parallel, then desk-verifier on each run.
• The MCP server is for a client or an agent framework that calls tools and does not run shell commands. A headless review through MCP runs for minutes; use the CLI for that.
• The engines are for a review with no person: a CI job, a scheduled agent, a back-test.

Where the CLI reads issues and PRs

Each command that reads or writes issues, PRs, reviews or labels does it through the Forge of the repository (src/forge.ts). forgeOf (src/store.ts) picks it from store in .desk/config.json:

store	Forge	Login
github (the default)	githubForge: the gh CLI, in src/github.ts	the active gh account, or GH_TOKEN
server	remoteForge: the HTTP API of the desk server	the token in the variable that server.tokenEnv names

No other file in src starts gh. The jobs of desk ci in GitHub Actions use the GitHub forge with the token of the run, which the action gives as GITHUB_TOKEN. desk doctor checks the access to the forge of the repository. desk update reads the releases of desk on the desk server of desk login (--no-server reads the GitHub release instead).

Model

The kit does not choose a model. A headless engine uses, in this order:

1. --model <name> on the command line.
2. review.models in .desk/config.json, for example {"claude": "opus", "codex": "gpt-6.1-sol", "opencode": "ollama/kimi-k3:cloud"}.
3. The default model of the client, from its own configuration.

--engine openai (any OpenAI-compatible endpoint in DESK_BASE_URL) has no default and needs a model.

What a headless reviewer can do

A headless reviewer reads untrusted code and PR text, so it gets read access only, and none of the person's own tools:

Engine	Read access	What is off
claude	Read, Grep, Glob in a temporary checkout of the reviewed commit	--restricted: no user, project or local settings, so no personal hooks; --strict-mcp-config: no MCP servers
codex	--sandbox read-only in the checkout	Each MCP server of the person's config is turned off by name
opencode	read, grep, glob, list in the checkout	Every other tool, including the tools of the person's MCP servers; edits, shell and web fetch are denied
openai	None: the diff is in the prompt	Everything

The checkout is a git worktree in a temporary folder. The kit removes it after the run, and a later run removes the checkout of a run that was killed.

Codex and MCP approvals

codex exec cannot ask a person to approve an MCP tool call, so it refuses the call. An interactive Codex session asks the person, which is the right default for post. For a headless Codex agent that must call the desk tools, set the approval for that server only:

codex exec -c 'mcp_servers.desk.default_tools_approval_mode="approve"' …