Installation

This guide describes the primary consumer install flow for agent-toolkit, then lists advanced methods when you need marketplace plugins, skills-only delivery, or manual file copies.

Prerequisites

The product CLI is the native V binary (GitHub Releases). uvx agent-toolkit-cli / PyPI still wrap that binary (ADR-021). Index: docs/v/README.md. Contributor build: docs/HOW_TO_DEVELOP_V.md.

Python 3.10 or later — optional unless you use the PyPI trampoline (uv / uvx)
At least one supported AI coding assistant:
- Claude Code (Anthropic)
- Cursor
- OpenCode
- GitHub Copilot (VS Code or JetBrains + extension)
- Windsurf (Codeium)
- Pi Coding Agent
- Muse Code (Meta)

Optional but recommended:

uv — preferred way to run uvx and manage the CLI
gh (GitHub CLI) — required by forge skills (gh-fix-ci, github-cli-workflow, etc.)
jq — used by several loop templates for JSON processing
node / npm — for MCP server installation and npx skills
git + bash — only needed for git-clone or install-script methods below

Swarms — `agent-toolkit swarm` prerequisites

Swarms are backend-neutral: the orchestration engine is filesystem-based, no cloud required. You need a UI backend and a runner:

UI backend (one required):
- Herdr — recommended. Rich workspace/tabs UI: brew install herdr or curl -fsSL https://herdr.dev/install.sh | sh. Verify herdr --version and herdr integration install opencode. See SWARM_HERDR.md.
- tmux — portable fallback, works over SSH/headless Linux. Install tmux via your package manager (brew install tmux, apt install tmux, etc.). Swarm uses an isolated server/socket per run agent-toolkit-swarm-<run-id> and never mutates your normal tmux sessions. See SWARM_TMUX.md.
- Use --backend auto (Herdr → tmux fallback) or explicitly --backend herdr / --backend tmux / --backend headless. swarm doctor reports herdr available, tmux available, versions, and opencode integration installed/outdated.
Runner (one required — provides the LLM):
- OpenCode — primary recommended runner (opencode models to list provider/model). Alternatives: claude, codex, cursor-agent, copilot, muse. Discover via agent-toolkit swarm models --runner opencode or agent-toolkit swarm runners. See SWARM_MODELS_AND_COSTS.md.
- Offline/fake demo: no runner or Herdr needed — use --runner skeleton (always available). agent-toolkit swarm start --runner skeleton --backend tmux --dry-run "demo task" previews without creating state; omit --dry-run for a real local run.
Git: required for worktree isolation. Each writing role gets worktrees/<role> on branch agent-toolkit-swarm/<run-id>/<role>; code moves via validated full 40-char SHAs.
Agentic-workstation auto-provision: if you use agentic-workstation, set agent_swarms.enabled=true to install tmux + Herdr + integrations automatically.

Check everything at once:

agent-toolkit swarm doctor
agent-toolkit swarm doctor --json
agent-toolkit swarm backends --json
agent-toolkit swarm runners --json

Primary install (recommended)

Graphical Desktop app

Download the latest Agent Toolkit Desktop release for Linux, macOS, or Windows. The Electron package includes the canonical backend, so a separate CLI install, source checkout, or developer toolchain is not required for normal Desktop use. Start with the Desktop product guide for onboarding, People, projects, Library, Operations, and terminal workflows.

The CLI install below is for terminal-first setup, scripting, CI, and headless workflows. Desktop users can perform their basic workspace setup from the GUI.

Support matrix: the single source is docs/TRUST.md#Installation channels — GitHub Releases (canonical artifact), PyPI, npm, Homebrew, AUR, GHCR container, Claude/Cursor marketplaces, Agent Plugins artifacts. The canonical artifact is the native V binary from a GitHub Release; PyPI/npm/marketplaces are distribution adapters, Homebrew/AUR are downstream packages that fetch the canonical artifact. V is canonical, Python is a thin launcher.

One command auto-detects your AI tools and deploys the right profiles. Pick one channel — all install the same V CLI.

# Homebrew
brew tap ulises-jeremias/homebrew-tap && brew install agent-toolkit
# AUR (native V; not the Python AUR package)
yay -S agent-toolkit-bin
# GitHub Release — download agent-toolkit-<os>-<arch> + SHA256SUMS from
# https://github.com/ulises-jeremias/agent-toolkit/releases/latest
# PyPI launcher (execs bundled V)
uv tool install 'agent-toolkit-cli>=1.11.0'
# npm
npm i -g agent-toolkit-cli

agent-toolkit install
agent-toolkit doctor

From a git checkout the canonical implementation is the V binary (#555, HOW_TO_DEVELOP_V.md):

./make.vsh install-cli    # <prefix>/bin/agent-toolkit; default ~/.local/bin
# custom prefix: ./make.vsh install-cli --prefix=/usr/local
agent-toolkit doctor --json

See docs/v/archive/cutover.md and docs/v/archive/rollback.md. PyPI/uvx ships a thin Python trampoline over the V binary (ADR-021; python-fallback.md). Do not retag empty v1.10.0.

Install options

# Specific tools only
agent-toolkit install --tools claude-code,cursor

# Preview changes without writing files
agent-toolkit install --dry-run

# Overwrite existing toolkit-managed files
agent-toolkit install --force

Verification

After the primary install:

agent-toolkit doctor
# Optional: shell completions (bash / zsh / fish / PowerShell)
agent-toolkit completion bash >> ~/.bashrc

Open your AI tool and ask: “What skills do you have available?” — responses should reflect the agent-toolkit skill set.

To validate skill definitions from a git checkout:

./scripts/validate-skills.vsh

Advanced install methods

Use these when the primary CLI flow does not fit your environment.

Claude Code plugin marketplace

Native plugins for Claude Code only:

/plugin marketplace add ulises-jeremias/agent-toolkit
/plugin install agent-toolkit-core@agent-toolkit
/plugin install agent-toolkit-agents@agent-toolkit
/plugin install agent-toolkit-forge@agent-toolkit

Cursor plugins (IDE + Agent CLI)

Native plugins from .cursor-plugin/marketplace.json: agent-toolkit-core, agent-toolkit-agents, agent-toolkit-forge.

Cursor IDE

Open Customize in the sidebar and choose Plugins → Add → From GitHub Repository.
Enter https://github.com/ulises-jeremias/agent-toolkit.
Install the plugins you need (agent-toolkit-core is the baseline) at user or project scope. See the current Cursor plugin guide.

User-scoped installs sync to Cursor Agent CLI sessions automatically.

Cursor Agent CLI

# Open Cursor Agent and use its current plugin install flow.
# See https://cursor.com/docs/plugins for the current CLI syntax and scope options.
cursor-agent

Load a local plugin directory for one session:

cursor-agent --plugin-dir ./plugins/agent-toolkit-core
cursor-agent --plugin-dir ./plugins/agent-toolkit-agents
cursor-agent --plugin-dir ./plugins/agent-toolkit-forge

Local / offline

mkdir -p ~/.cursor/plugins/local
ln -s "$(pwd)/plugins/agent-toolkit-core" ~/.cursor/plugins/local/agent-toolkit-core
ln -s "$(pwd)/plugins/agent-toolkit-agents" ~/.cursor/plugins/local/agent-toolkit-agents
ln -s "$(pwd)/plugins/agent-toolkit-forge" ~/.cursor/plugins/local/agent-toolkit-forge

See Cursor plugins docs.

npx skills (skills only)

Installs skills via the Agent Skills standard. Does not deploy agents, loops, or full profiles.

npx skills add ulises-jeremias/agent-toolkit -g

Homebrew / AUR

brew tap ulises-jeremias/homebrew-tap && brew install agent-toolkit
yay -S agent-toolkit-bin   # Arch Linux (AUR) — GitHub Release V binary
npm i -g agent-toolkit-cli # npm optionalDependencies platform packages @1.11.0

Git clone (from-source CLI)

For offline installs or pinning a specific commit, build/install the V CLI from the checkout (ADR-007 removed the deprecated scripts/install.sh wrapper):

git clone https://github.com/ulises-jeremias/agent-toolkit ~/.agent-toolkit
cd ~/.agent-toolkit
./make.vsh install-cli    # → ~/.local/bin/agent-toolkit (or --prefix=…)
agent-toolkit install
# Or via the PyPI trampoline against the same checkout:
# uvx --from agent-toolkit-cli --from ~/.agent-toolkit agent-toolkit install

Manual install

Copy profiles yourself when you need full control over paths. Clone the repo first:

git clone https://github.com/ulises-jeremias/agent-toolkit ~/.agent-toolkit

Claude Code

mkdir -p ~/.claude/agents
cp ~/.agent-toolkit/profiles/claude-code/CLAUDE.md ~/.claude/CLAUDE.md
cp ~/.agent-toolkit/profiles/claude-code/settings.json ~/.claude/settings.json
cp -r ~/.agent-toolkit/profiles/claude-code/agents/. ~/.claude/agents/

Restart Claude Code. Agents are available via @agent-name (e.g. @code-reviewer).

Project-level (overrides global):

cd /path/to/your/project
mkdir -p .claude/agents
cp ~/.agent-toolkit/profiles/claude-code/CLAUDE.md .claude/CLAUDE.md
cp ~/.agent-toolkit/profiles/claude-code/settings.json .claude/settings.json

Cursor

mkdir -p ~/.cursor/rules
cp -r ~/.agent-toolkit/profiles/cursor/rules/. ~/.cursor/rules/

Per-project: copy to .cursor/rules/ inside your repo instead.

OpenCode

mkdir -p ~/.config/opencode/agents
cp ~/.agent-toolkit/profiles/opencode/opencode.json ~/.config/opencode/opencode.json
cp -r ~/.agent-toolkit/profiles/opencode/agents/. ~/.config/opencode/agents/

GitHub Copilot

Per-project, committed to the repository:

cd /path/to/your/project
mkdir -p .github
cp ~/.agent-toolkit/profiles/copilot/copilot-instructions.md .github/copilot-instructions.md

Windsurf

WINDSURF_DIR="${HOME}/.codeium/windsurf"
[ -d "$WINDSURF_DIR" ] || WINDSURF_DIR="${HOME}/.windsurf"
mkdir -p "${WINDSURF_DIR}/rules" "${WINDSURF_DIR}/memories"
cp -r ~/.agent-toolkit/profiles/windsurf/rules/. "${WINDSURF_DIR}/rules/"
cp ~/.agent-toolkit/profiles/windsurf/memories/global_rules.md "${WINDSURF_DIR}/memories/global_rules.md"

Pi Coding Agent

mkdir -p ~/.pi/agent/skills
cp -r ~/.agent-toolkit/profiles/pi/skills/. ~/.pi/agent/skills/

MCP setup

MCP gives your AI tool access to external services (GitHub, Slack, Linear, etc.). See MCP.md for per-tool config locations and provider setup.

Staying up to date

Match the channel you installed:

brew upgrade agent-toolkit
# AUR
yay -Syu agent-toolkit-bin
# PyPI launcher
uv tool upgrade agent-toolkit-cli
# npm
npm update -g agent-toolkit-cli
# GitHub Release: download the new binary + SHA256SUMS from /releases/latest

agent-toolkit install --force

From a git checkout:

cd ~/.agent-toolkit && git pull && ./make.vsh install-cli && agent-toolkit install --force

Back up customized profile files before --force. See MIGRATION.md when switching from profile-copy installs to marketplace plugins.

Data packaging and resolution

The product CLI is the native V binary. Homebrew and AUR consume GitHub Release assets (distribution/, ADR-023/024). The PyPI launcher wheel still bundles capability data; resolution order for that path is ADR-005 / ADR-015.

Troubleshooting

Claude Code: skills not loading

head -5 ~/.claude/CLAUDE.md

Project-level .claude/CLAUDE.md overrides global. Restart Claude Code after changes.

Cursor: rules not appearing

Confirm .mdc files are in ~/.cursor/rules/ (global) or .cursor/rules/ (project)
Verify YAML frontmatter (---, description:, closing ---)
Restart Cursor

Windsurf: rules not loading

Try ~/.windsurf/ if ~/.codeium/windsurf/ does not exist for your version.

OpenCode: agents not available

ls ~/.config/opencode/agents/

Restart OpenCode after adding agent files.

MCP servers not connecting

Confirm the server binary is on $PATH
Confirm env vars (e.g. GITHUB_TOKEN) are set in the shell your AI tool uses
Check MCP logs in your tool for connection errors

validate-skills.vsh fails

Error	Fix
Missing `SKILL.md`	Add `SKILL.md` to the skill directory
Missing frontmatter `name`	Add `name:` to the `---` block in `SKILL.md`
Missing frontmatter `description`	Add `description:` to the `---` block
Secret pattern detected	Remove the credential; use `${ENV_VAR}` placeholders

Guide	Description
TARGETS.md	Supported compile targets and capability matrix
MIGRATION.md	Move from profile-copy to native plugins
MCP.md	MCP provider setup

See also: TROUBLESHOOTING.md for doctor error recipes.

Installation

Installation

Prerequisites

Swarms — agent-toolkit swarm prerequisites

Primary install (recommended)

Graphical Desktop app

Install options

Verification

Advanced install methods

Claude Code plugin marketplace

Cursor plugins (IDE + Agent CLI)

npx skills (skills only)

Homebrew / AUR

Git clone (from-source CLI)

Manual install

Claude Code

Cursor

OpenCode

GitHub Copilot

Windsurf

Pi Coding Agent

MCP setup

Staying up to date

Data packaging and resolution

Troubleshooting

Claude Code: skills not loading

Cursor: rules not appearing

Windsurf: rules not loading

OpenCode: agents not available

MCP servers not connecting

validate-skills.vsh fails

Related guides

Swarms — `agent-toolkit swarm` prerequisites