README
Agent Alchemy
A plugin suite and developer toolkit that extends Claude Code into a structured development platform — from specs to tasks to autonomous execution.
What is Agent Alchemy?
Agent Alchemy is an open-source toolkit for AI and software engineers who use Claude Code. It adds structured development workflows on top of Claude Code through six plugins, a real-time task manager, and a VS Code extension — all designed to work together as an integrated pipeline.
Everything is built with Claude Code for Claude Code. The plugins are plain markdown — readable, editable, and version-controlled like any other code.
Components
Claude Code Plugins
Six plugin groups providing 28 skills and 16 agents:
| Plugin | Description |
|---|---|
| SDD Tools | Spec-Driven Development — turn ideas into specs, specs into tasks, and tasks into autonomous execution |
| Dev Tools | Feature development, code review, architecture patterns, documentation, and changelog management |
| Core Tools | Codebase analysis, deep exploration with multi-agent teams, and language patterns |
| TDD Tools | Test-Driven Development — RED-GREEN-REFACTOR workflows, test generation, and coverage analysis |
| Git Tools | Conventional Commits automation |
| Plugin Tools | Plugin porting, adapter validation, ported plugin maintenance, and ecosystem health analysis |
Task Manager
A Next.js real-time Kanban dashboard for monitoring autonomous task execution. Tasks update live via filesystem watching and Server-Sent Events.
See more screenshots screenshots below
VS Code Extension
Schema validation, YAML frontmatter autocomplete, and hover documentation for Claude Code plugin development.
Getting Started
Prerequisites
- Claude Code CLI installed
- Node.js >= 18.0.0
- pnpm >= 8.0.0
Install Plugins
# Install from the Claude Code marketplace
claude plugins install agent-alchemy/agent-alchemy-sdd-tools
claude plugins install agent-alchemy/agent-alchemy-dev-tools
claude plugins install agent-alchemy/agent-alchemy-core-tools
claude plugins install agent-alchemy/agent-alchemy-git-tools
claude plugins install agent-alchemy/agent-alchemy-tdd-tools
claude plugins install agent-alchemy/agent-alchemy-plugin-tools
Run Task Manager
pnpm install
pnpm dev:task-manager
# Open http://localhost:3030
Build VS Code Extension
cd extensions/vscode
npm install
npm run build
npm run package
Configuration
Plugin behavior is configured via .claude/agent-alchemy.local.md — a markdown file with nested key-value pairs using key: value syntax. This file is not committed to version control.
File Format
- deep-analysis:
- direct-invocation-approval: true
- invocation-by-skill-approval: false
- execute-tasks:
- max_parallel: 5
- author: Your Name
- spec-output-path: specs/
Settings Reference
| Setting | Plugin | Default | Description |
|---|---|---|---|
deep-analysis.direct-invocation-approval | core-tools | true | Require user approval of the team plan when invoking /deep-analysis directly |
deep-analysis.invocation-by-skill-approval | core-tools | false | Require approval when deep-analysis is loaded by another skill (e.g., /feature-dev, /codebase-analysis) |
execute-tasks.max_parallel | sdd-tools | 5 | Maximum concurrent task-executor agents per wave. CLI --max-parallel takes precedence. Set to 1 for sequential execution |
author | sdd-tools | — | Author name for spec attribution and task metadata |
spec-output-path | sdd-tools | specs/ | Default directory for spec file output |
Precedence
Settings follow this precedence order (highest to lowest):
- CLI arguments (e.g.,
--max-parallel) .claude/agent-alchemy.local.mdsettings- Built-in defaults
Architecture
Agent Alchemy follows a markdown-as-code philosophy — "prompts as software" — where AI agent behaviors, workflows, and domain knowledge are defined entirely in Markdown with YAML frontmatter. There is no compilation step; the markdown files are the executable code, interpreted directly by Claude Code's runtime.
Three Interconnected Systems
Plugin Framework (claude/) Task Dashboard (apps/task-manager/)
28 skills, 16 agents Next.js 16 + TanStack Query
6 plugin groups Real-time Kanban via SSE
markdown-as-code Watches ~/.claude/tasks/
│ ▲
│ creates task JSON files │ watches filesystem
└────────────────────────────────────┘