Skip to content

Install and connect an agent

deputy has two parts: the deputy command (the MCP server) and a model server it talks to (llama.cpp, Ollama, vLLM, LM Studio, or a hosted OpenAI-compatible API). You need both.

1. Install

One line, no sudo, everything stays in your home directory:

curl -LsSf https://raw.githubusercontent.com/tommasomarchionni/deputy/main/install.sh | sh

The script is short; read it first if you like. It needs uv; add -s -- --install-uv to let it install uv too (a pinned version of the official uv installer, checked against its SHA-256 before it runs):

curl -LsSf https://raw.githubusercontent.com/tommasomarchionni/deputy/main/install.sh | sh -s -- --install-uv

Prefer not to pipe a script? Same result, by hand:

uv tool install git+https://github.com/tommasomarchionni/deputy

Pin a version with DEPUTY_REF=v0.1.0. Remove it with sh install.sh --uninstall (your config and traces are kept).

The installer picks the latest release (the wheel built and attested by the release workflow; main if there is none yet). Update later with deputy update; see configuration for automatic updates.

2. Point it at a model

deputy init          # asks for the URL, model name and an optional key file
deputy doctor        # checks the config and that the server answers

Non-interactive: deputy init --yes --url http://127.0.0.1:8080 --model default. Details and examples for each kind of server: configuration.

3. Connect your agent

deputy install <agent> prints the exact configuration; add --apply to do it for you.

Agent Command What --apply does
Claude Code deputy install claude-code --apply runs claude mcp add --scope user deputy -- deputy mcp
GitHub Copilot (VS Code) deputy install vscode --apply adds the server to .vscode/mcp.json of the current project
Cursor deputy install cursor --apply adds it to .cursor/mcp.json
Codex CLI deputy install codex prints a TOML block for ~/.codex/config.toml
Anything else that speaks MCP deputy install generic prints a JSON block; the command is deputy mcp over stdio

Restart the agent (or reload its MCP servers) afterwards.

The read hint (Claude Code, on by default). deputy install claude-code --apply also adds a hook to ~/.claude/settings.json: before Claude Code reads a whole file larger than about 8 KB (about 2,000 tokens), it adds one line to the model's context with the file's size and a reminder that deputy can read it instead. It never blocks a read, says nothing for a partial or small read, and stays silent on any error. In real sessions such reads were about 1.5 % of all reads but held about 18 % of what was read. Turn it off with deputy hook off (on again with deputy hook on, state with deputy hook status), or install without it: deputy install claude-code --apply --no-hook.

4. Teach the agent when to delegate

Delegation only saves tokens if the agent uses it on the right work. One command writes a short guide in the format each agent reads:

deputy instructions --for claude --apply        # Claude Code skill: loaded only when relevant
deputy instructions --for copilot --apply       # GitHub Copilot: .github/instructions/deputy.instructions.md
deputy instructions --for cursor --apply        # Cursor rule
deputy instructions --for agents --apply        # AGENTS.md (Codex, Copilot and many others)
--for File written (in the current project) Kind
claude .claude/skills/deputy/SKILL.md owned by deputy; a skill costs no tokens until it is relevant
claude-md CLAUDE.md a marked block; always loaded
copilot .github/instructions/deputy.instructions.md owned; applyTo: "**"
copilot-repo .github/copilot-instructions.md a marked block
cursor .cursor/rules/deputy.mdc owned; attached when relevant
agents AGENTS.md a marked block

Without --apply the command only prints what it would write. Files deputy owns are rewritten each time; in shared files only the block between the deputy:start and deputy:end markers is touched, so your own text is safe. Prefer claude over claude-md: a skill is loaded on demand, a CLAUDE.md block on every turn.

The guide is short on purpose (about 450 tokens). It says what to delegate and what not, how to write checks, what to trust (status: ok) and what to do yourself, to review worker output, and to send feedback.

5. Try it

Ask your agent: "Use deputy to summarise README.md in five bullets, citing lines." The result carries status, the answer and a one-line summary of the checks that ran; metrics and the saving estimate are in the trace (deputy stats).

Troubleshooting

  • deputy doctor says the key was refused: the model server wants an API key; set api_key_file (mode 600) or api_key_env in the config.
  • command not found: deputy: run uv tool update-shell and open a new terminal.
  • The agent does not list the tools: restart it; run deputy mcp by hand and it should wait silently on stdin (stop it with Ctrl-D).
  • Slow answers: see local serving; reasoning models spend most of the time thinking, and capping that is the biggest lever.