One source → many assistants
Agent Toolkit is the L1.5 capability catalog for the Personal DX graph.
Write a skill, agent, or loop once; compile it into every supported tool target.
Stack position
L1.5 in the Personal DX graph
Workstation provisions the machine. Toolkit distributes capabilities. Overlay/harness holds memory and run state. Edges are graph-like — HorneroConfig is an optional desktop surface, not a mandatory linear step.
- L1Workstationmachine · provisioning
- L1.5Toolkitcapabilities · distribution
- L2Harnessruntime · memory
- L0HorneroConfigoptional desktop sibling
Workstation · toolkit · overlay
L1 provisions the machine. L1.5 distributes capabilities. The overlay holds memory and run state.
Precedence is project overlay → toolkit defaults. HorneroConfig is an optional desktop sibling, not a hard dependency.
Delivery, not demo
Capabilities ship for agentic harnesses: budgets, handoffs, inventories, and doctor checks.
Install is one command; verification is inventory + doctor — not marketing counters.
Capability anatomy
Skills · agents · loops · packs · plugins · MCP
One catalog, six capability families. Counts verified against agent-toolkitb6700ca (2026-08-07) — inventory facts, not telemetry.
- 61skills9 domains · core 8
- 16agentspersona constraints
- 10loopsL1 / L2 / L3
- 7profilesnative tool targets
- 6MCPregistry templates
- 61SkillsReusable capability units — one SKILL.md directory each.core 8 · delivery 21 · forge 8 · design 6 · ops 6 · integrations 5 · tooling 4 · data 2 · loops 1
- 16AgentsPersona constraints that scope allow/deny actions and handoffs.architect · planner · code-reviewer · security-reviewer · tdd-guide · …
- 10LoopsRecurring workflows declared as loops/<name>/loop.yaml.L1 report-only · L2 controlled · L3 high-autonomy · resumable budgets
- 3PacksClient/project context bundles loaded into the harness overlay.delivery-discipline · engineering-workflow · oss-maintenance
- 4PluginsNative marketplace products compiled from the same catalog.agent-toolkit-core · agents · forge · complete
- 6MCPRegistry + installable templates for external tool servers.github · slack · clickup · linear · notion · figma
Skill domains — core is 8, not 6
- core8
- delivery21
- forge8
- design6
- ops6
- integrations5
- tooling4
- data2
- loops1
Source → targets
Compile once. Land in seven native profiles.
skills/, agents/, and loops/ are the source of truth. Profiles underprofiles/ are compiled views for each assistant — verified at b6700ca.
Source
agent-toolkit catalog
- skills/ · 61
- agents/ · 16
- loops/ · 10
- packs/ · 3
- plugins/ · 4
- mcp/ · 6
- Claude Code~/.claude/skills + marketplace plugins
- Cursorprofiles/cursor/rules/*.mdc
- OpenCodeprofiles/opencode/agents + opencode.json
- Copilotprofiles/copilot
- Windsurfprofiles/windsurf/memories
- Piprofiles/pi/skills
- Muse Codeprofiles/muse-code
Distribution is graph-like: the workstation provisions the machine; the toolkit compiles capability; overlays hold memory. No skill is copied by hand into each tool.
Queue ≠ swarm
DevCompanion queues work. Swarm orchestrates roles.
Mixing them is the most common mental model bug. The queue persists jobs; the swarm runs a recipe topology with isolated worktrees and governance over shared state files.
DevCompanion — durable queue
Background job queue for heavy work: review, PR, CI fix, investigate, refactor. Not a multi-agent runtime.
- queue → outbox → run-once → status / done / log
- Templates: code-review, create-pr, fix-ci, investigate, refactor
- LLM policy gate before client jobs (llm-status)
agent-toolkit devcompanion queue <project> --template code-review
Swarm — multi-role orchestration
Recipe-driven role topology with isolated worktrees, SHA handoffs, budgets, and governance. Separate from the queue.
- REQUEST → recipe → roles → worktrees → handoffs → state → governance → artifact
- pair / team / full recipes with promote without losing run ID
- Herdr and tmux are UI backends over the same run state
agent-toolkit swarm plan --recipe pair --ui tmux "…" --json
Swarm story
Request → recipe → roles → worktrees → handoffs → state → governance → artifact
Multi-role orchestration is separate from DevCompanion’s queue. Pick a recipe — the same stage pipeline stays; only the role topology changes. Herdr and tmux are two views of one run state.
- 01RequestA concrete task enters the swarm planner.swarm plan --recipe <pair|team|full>
- 02RecipeTopology is selected by risk; roles stay inactive until inputs are ready.pair · team · full — promote preserves run ID
- 03RolesEach role maps to a persona, policy, and model profile.policies: read-only · writer · reviewer-writer · integrator
- 04WorktreesIsolated git worktrees per active role — no shared dirty trees.one worktree per role · runner skeleton or live
- 05HandoffsCode moves only via validated 40-char commit SHAs.never uncommitted code · receive_mode task|batch
- 06Staterun.yaml, trace.jsonl, budget.json, ownership, and approvals.atomic writes · fail closed on unclear ownership
- 07GovernanceBudgets, permissions, and human approval gates.push/release/base-merge denied by default
- 08ArtifactReviewable outputs: diffs, plans, reports, and logs.swarm status / logs / artifacts for the run
Herdr · tmux — same state, two views
Shared run state
- run.yaml
- trace.jsonl
- budget.json
- ownership.json
- approvals.json
- artifacts/
Herdr
Preferred workspace GUI over the same run state, approvals, and artifacts.
tmux
Terminal panes on an isolated socket — parity view, not a fork of the product.
Install · budgets
Ship the catalog, then constrain the swarm
Install
uvx --from agent-toolkit-cli agent-toolkit install
agent-toolkit doctor
uv tool install agent-toolkit-cli
agent-toolkit install
/plugin marketplace add ulises-jeremias/agent-toolkit
/plugin install agent-toolkit-core@agent-toolkit
Budgets
- tokens
max_total_tokens / max_role_tokens— cap per run- cost
max_cost_usd— spend gate- time
max_wall_seconds— wall-clock limit- concurrency
max_concurrency 2— parallel roles- round-trips
max_role_round_trips 2— pair default- artifacts
artifact_size + handoffs— size gates