A Claude Code plugin providing a coordinated team of specialized subagents.
AI-Pack turns a Claude Code session into an engineering team. It ships seven specialized subagents (architect, engineer, inspector, pr-shepherd, product-manager, reviewer, spelunker), four workflow skills (orchestrate, prd, pre-push, shepherd-pr), and a knowledge-graph MCP server (kg) that gives agents persistent memory of your codebase. Claude Code provides the execution loop; AI-Pack provides the roles, the coordination patterns, and the memory.
Prerequisites: Claude Code installed and working. macOS or Linux.
In any Claude Code session:
/plugin marketplace add Cortexa-LLC/ai-pack
/plugin install ai-pack@ai-pack
Restart Claude Code when prompted. That's it — no clone, no toolchain, no terminal
steps. The subagents are then available via the Agent tool as ai-pack:<name>, and
the skills trigger automatically or via /ai-pack:<skill>.
To update later: /plugin marketplace update ai-pack.
The kg server gives agents persistent memory, and the plugin resolves it on its own
(see Knowledge Graph). If it can't be found, everything still
works — agents simply run without persistent memory, silently. Nothing errors and no
setup step is required to get value from the plugin. Check /mcp or /plugin →
Errors to see kg's status.
Today kg is found only if it is already on your PATH or named by $AI_PACK_KG; the
automatic download activates once prebuilt releases are published (see
ADR-010). To install it now, build from source at
Cortexa-LLC/mcp and put the binary on PATH.
Contributors work from a clone; this is not the user path.
git clone https://github.com/Cortexa-LLC/ai-pack.git
cd ai-pack
make install-plugin # registers the LOCAL checkout as a marketplace
make update-plugin # force-resync the installed copy after editing plugin/Seven subagents live in plugin/agents/. Each is a self-contained role definition with its own tool discipline, quality gates, and reporting format.
| Agent | What it does | Example invocation |
|---|---|---|
| architect | Technical design: module boundaries, API contracts, data models, ADRs | "design the architecture for the notification system" |
| engineer | Implementation: writes code, fixes bugs, creates tests | "implement the authentication feature" |
| inspector | Root-cause analysis for complex bugs; produces a fix specification | "investigate why the payment processor occasionally returns 500" |
| pr-shepherd | Drives a GitHub PR to merge-ready: watches CI, fixes failures, answers reviewer threads | "shepherd PR #42 to merge-ready" |
| product-manager | Product requirements: PRDs with measurable goals, non-goals, epics, and user stories with testable acceptance criteria | "write a PRD for the notification system from this discovery transcript" |
| reviewer | Code review: quality, security, best practices, structured findings with severities | "review the auth handler for security issues" |
| spelunker | Codebase investigation: traces execution paths, maps dependencies, answers "how does X work" | "trace the execution path for this failing test" |
Spawn them from any Claude Code session:
Use the Agent tool with subagent_type "ai-pack:engineer" and a fully
self-contained prompt — subagents share no memory with your session.
Four skills in plugin/skills/ package multi-agent workflows:
- orchestrate — decomposes engineering work and delegates it to the subagents. Triggers on multi-step requests like "build this feature end to end" or "investigate why X is broken then fix it".
- prd — product discovery interview in the main session (subagents cannot question the user), then delegates PRD drafting to the product-manager agent. The finished PRD lands in
docs/product/. Triggers on "create a PRD" or "help me spec this feature". - pre-push — review-and-fix loop on local commits before pushing. Spawns a reviewer against the local diff; if issues are found, spawns an engineer to fix them, amends, and re-reviews until approved. Triggers on "review my commits before I push".
- shepherd-pr — drives an open GitHub PR to a green, approved, mergeable state. Triggers on "shepherd PR #42" or "drive my PR to green".
There are three ways to shepherd a PR — this skill, the pr-shepherd agent, and a repo-local deterministic workflow. docs/SHEPHERDING.md covers which to use when, and why the workflow variant cannot ship with the plugin.
Agent briefs are passed directly in Agent-tool prompts. For multi-session work where a brief must outlive any single session, an optional two-file convention under .ai/tasks/<slug>/ is available:
task.md— the orchestrator's brief: what to do, files to change, acceptance criteria, constraints, context. Fully populated, never template placeholders.result.md— written by the agent when done: findings, decisions, blockers.
Templates live in templates/task-packet/. Additional document templates (ADRs, incident reports, investigations, security docs, PRDs) are in templates/.
plugin/.mcp.json launches kg — an MCP server that indexes your codebase into a
persistent knowledge graph. Agents query it for file context, entity relationships, and
observations accumulated across sessions.
The plugin finds kg for you. plugin/bin/kg-launch.sh resolves a binary in this
order, and the first hit wins:
$AI_PACK_KG, if set — explicit override, and the air-gapped escape hatch.kgonPATH— a source build always beats the pinned release, so contributors keep testing their own binary.~/.ai-pack/bin/kg-<version>/kg— a previously downloaded copy.- Download the release pinned in
plugin/kg.lock.json, verify itssha256, cache it.
Step 4 is inert until prebuilt kg releases exist — kg.lock.json ships with an empty
pin, so today the launcher uses steps 1–2 only. See
ADR-010 for the full design.
Absence is not an error. If no binary is found, the launcher exits non-zero with one
diagnostic line, Claude Code lists kg under /plugin → Errors, and the session runs
without kg__* tools. Every agent and skill treats that as a defined, silent
degradation: KG steps are skipped, nothing is retried, and the absence is not reported
as a problem. The knowledge graph is an accelerator, never a dependency.
Verify a local install with scripts/verify-kg.sh. To clear the download cache, remove
~/.ai-pack/bin/.
plugin/ The product: agents/, skills/, .mcp.json
.claude-plugin/ Local marketplace definition (marketplace.json)
templates/ ADR, incident, investigation, security, task-packet, PRD templates
scripts/ Billing checkers, kg verification, submodule reset
docs/ Docusaurus documentation site (docs/website)
assets/ Logos and banners
mcp/ Git submodule providing the kg binary
Once provisioned, every same-repo, non-draft pull request gets an advisory review
from Claude (.github/workflows/claude-pr-review.yml). The workflow installs the
Claude Code CLI on the runner and runs claude -p directly — no GitHub App
installation is required. The system prompt is the ai-pack reviewer role
(plugin/agents/reviewer.md), loaded from the base branch so a PR cannot tamper
with the prompt that reviews it; existing review threads are fed back in so
repeated pushes don't re-raise the same findings. Claude posts one review per run
with severity-graded findings and a verdict: approve (zero Critical and zero
Major findings), comment, or request changes. The verdict participates in branch
protection through the required Claude verdict status check, which fails
only on a request-changes verdict (GitHub ignores App approvals for
required-review counts, so a review requirement cannot express this). The
review job itself stays advisory — a runtime failure or missing token never
turns the PR red or blocks merge. Merging always remains a human action;
GitHub auto-merge must never be enabled on this repository.
Provisioning (one-time, subscription-funded; no metered API key):
- Mint and store the OAuth token:
claude setup-token # mint a long-lived OAuth token locally
gh secret set CLAUDE_CODE_OAUTH_TOKEN # store it as a repo Actions secret-
Optional — proper bot identity: set
CORTEXA_LLC_REVIEWER_APP_IDandCORTEXA_LLC_REVIEWER_PRIVATE_KEY(credentials of the org's reviewer GitHub App) as repo Actions secrets. With them, reviews post as the reviewer bot; without them, the workflow degrades gracefully and reviews post asgithub-actions[bot]. -
Branch protection (lives outside the workflow file): add Claude verdict to main's required status checks. In a solo-maintainer repository, also remove any required-approving-review rule — GitHub does not count App approvals toward it, so it can only ever be satisfied by admin bypass. The check reads only the review on the current head, so stale verdicts never gate.
Until the OAuth secret exists, the review job skips cleanly (never a red check). Rotate the token by re-running step 1.
Fork posture: the workflow triggers on pull_request only (never
pull_request_target) and runs only for same-repo, non-draft PRs, so the OAuth
token is never exposed to fork PRs. Fork contributions are reviewed by humans or by
a maintainer pushing the branch into the repo.
The 3.x plugin needs no per-project integration — no submodule, no hooks, no copied commands. Install it once (make install-plugin) and it works in every project; the knowledge graph creates .ai/knowledge.db per project automatically on first use.
If you previously integrated the 2.x server, two cleanup scripts remove exactly what the old installer placed (both support --dry-run):
# Once per machine: stop services, remove binaries and MCP registration
# (archives your task history first; --purge also removes ~/.ai-pack)
bash scripts/uninstall-server.sh
# Once per integrated project, from that project's root: remove the
# .ai-pack submodule, ai-pack slash commands, hooks, rules, and template
# skills — preserving .ai/ (knowledge graph + task history) and your CLAUDE.md
bash /path/to/ai-pack/scripts/uninstall-project.shAfter cleanup, review the project's CLAUDE.md by hand if it was copied from the 2.x template — the scripts flag it but never edit it.
AI-Pack 1.x/2.0 was an API-driven agent server: a Go server on port 8082 running coding agents against the Claude API, with an agent CLI, an agent-mcp MCP server, and a React GUI. That architecture was deprecated on 2026-08-22 in favor of the plugin model — Claude Code natively provides the execution loop the server used to implement. The server-era code is preserved at tag v2.0-server-final.