Getting Started

The fastest path from install to your first successful skill use.

Prefer a graphical setup? Install Agent Toolkit Desktop from the latest GitHub Release and follow its in-app workspace setup. Desktop bundles the backend; basic use does not require a separate CLI, a repository checkout, or manual config edits. See the Desktop guide for workflows and current limits.

1. Install (pick one channel — all end on the same V CLI)

# GitHub Release binary (native V) — see docs/INSTALLATION.md
# Homebrew
brew tap ulises-jeremias/homebrew-tap && brew install agent-toolkit
# AUR
yay -S agent-toolkit-bin
# PyPI launcher (execs bundled V; ADR-021)
uv tool install agent-toolkit-cli
# npm
npm i -g agent-toolkit-cli

agent-toolkit install

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

./make.vsh install-cli    # ~/.local/bin/agent-toolkit (or --prefix=/usr/local)
agent-toolkit doctor --json

PyPI/uvx is a thin trampoline over the bundled V binary (ADR-021). insights / release are not ported (advanced-command-disposition.md). Rollback: docs/v/archive/rollback.md.

See docs/INSTALLATION.md for full options.

2. Verify with doctor

agent-toolkit doctor

Expected: all detected tools show installed and healthy. If a tool is missing, install it first (e.g. Claude Code, Cursor, OpenCode).

3. Install core profile/plugin

agent-toolkit install --tools claude-code
# Check what is installed
agent-toolkit inventory

For Claude Code marketplace (alternative): /plugin marketplace add ulises-jeremias/agent-toolkit then /plugin install agent-toolkit-core@agent-toolkit.

4. Open a supported tool

Open Claude Code (or your tool from agent-toolkit doctor output) and confirm the plugin/skill is listed:

agent-toolkit inventory --tool claude-code

5. Invoke one named core skill

In your AI tool, invoke an existing core skill — e.g. core/assistant:

> Use the core/assistant skill to bootstrap this workspace

You should see the assistant skill instructions load. Browse the full catalog: catalogs/skill-catalog.yaml (103+ skills), regenerate with ./scripts/generate-catalogs.vsh.

6. Try Swarms (optional — multi-agent orchestration)

Swarms coordinate multiple coding-agent sessions with isolated Git worktrees and durable handoffs. Herdr is recommended, tmux is the portable fallback, and --runner skeleton lets you explore fully offline.

# Check swarm prerequisites (Herdr, tmux, runners, git)
agent-toolkit swarm doctor
agent-toolkit swarm backends --json
agent-toolkit swarm runners

# Explore recipes: pair (default), team, full
agent-toolkit swarm recipes
agent-toolkit swarm recipe show pair
agent-toolkit swarm models --runner opencode   # provider/model discovery

# Side-effect free dry-run — no worktrees, no LLM needed
agent-toolkit swarm start --recipe pair --backend headless --runner skeleton --dry-run "Demo: add hello endpoint"

# Start a swarm — Herdr (recommended)
agent-toolkit swarm start --recipe pair --backend herdr --runner opencode --model-profile balanced "Implement issue #123"
# tmux fallback (works over SSH/headless)
agent-toolkit swarm start --recipe pair --backend tmux --runner opencode --model-profile balanced "Fix bug #42"

# Observe & operate
agent-toolkit swarm list
agent-toolkit swarm status RUN_ID --json
agent-toolkit swarm handoffs RUN_ID
agent-toolkit swarm artifacts RUN_ID
agent-toolkit swarm logs RUN_ID implementer
agent-toolkit swarm promote RUN_ID --to team   # elastic pair→team→full
agent-toolkit swarm approve RUN_ID plan # human gate

pair — implementer → reviewer/integrator → human approval (bugs, features).
team — planner → implementer → reviewer → architect → human approval (medium features, requires plan approval).
full — planner → implementer → refactorer → architect → hardener → QA → human approval (security/releases).
Budgets: max_total_tokens, max_cost_usd, max_wall_seconds, concurrency/round-trip limits. Human gates: plan, architecture, cost escalation, final integration. State under .agent-toolkit/swarm/runs/<run-id>/.

Details: SWARMS.md (overview + quickstart), SWARM_ARCHITECTURE.md (diagrams + state machines), SWARM_HERDR.md (Herdr UI), SWARM_TMUX.md (tmux fallback), SWARM_MODELS_AND_COSTS.md (models/budgets), SWARM_SECURITY.md (permissions/privacy).

Prerequisites: see INSTALLATION.md — Swarms prerequisites for Herdr/tmux/runner setup, or agent_swarms.enabled=true in agentic-workstation for auto-provision. Offline: --runner skeleton + --backend tmux works without Herdr or an LLM.

Next steps

Agent Definitions: see agents/ and the generated catalogs/agent-catalog.yaml.
MCP: see mcp/ templates (placeholders only; add credentials locally).
Advanced CLI: see SCOPE.md and CLI surfaces for progressive command discovery.
Loops: see loops/ and how to create a loop.
Swarms: see SWARMS.md, SWARM_ARCHITECTURE.md, and how to create a swarm recipe.
Contributing: see CONTRIBUTING.md for local setup and CI checks.

Troubleshooting

agent-toolkit doctor reports a missing tool → install that tool first.
inventory is empty → re-run agent-toolkit install with --force.
A package channel is unavailable → use Homebrew, AUR agent-toolkit-bin, GitHub Releases, uv tool install agent-toolkit-cli, or npm i -g agent-toolkit-cli.

See also: TROUBLESHOOTING.md for doctor error recipes.

Getting started