hatch3r

Crack the egg. Hatch better agents.

hatch3r is an open-source CLI and Cursor plugin that installs a battle-tested, tool-agnostic agentic coding setup into any repository. One command gives you up to 16 agents, 25 skills, 22 rules, 34 commands, and MCP integrations -- optimized for your coding tool of choice. Selective init installs only what you need based on your project type and team size.

Quick Start

Requires Node.js 22+.

npx hatch3r init

That's it. hatch3r detects your repo, asks about your project context (greenfield/brownfield, solo/team), lets you choose a content profile (minimal/standard/full/custom), and generates everything. The platform (GitHub, Azure DevOps, or GitLab) is auto-detected from your git remote. Run into issues? See Troubleshooting.

What You Get

Category	Count	Highlights
Agents	16	Code reviewer, test writer, security auditor, implementer (sub-agentic), fixer, researcher, architect, DevOps, and more
Skills	25	Bug fix, feature implementation, issue workflow, release, incident response, context health, cost tracking, recipes, API spec, CI pipeline, migration, customization, and more
Rules	22	Code standards, testing, API design, observability, theming, i18n, security patterns, agent orchestration, deep context analysis, and more
Commands	34	Board management, planning (feature, bug, refactor, test), workflow, quick-change, revision, debug, healthcheck, security-audit, cost-tracking, onboard, benchmark, customization, and more
MCP Servers	10 (3 default + 7 opt-in)	Playwright, Context7, Filesystem (default); GitHub, Brave Search, Sentry, Postgres, Linear, Azure DevOps, GitLab (opt-in)
Platforms	3	GitHub, Azure DevOps, GitLab -- auto-detected from git remote

Supported Tools (14 Adapters)

Tool	Output
Cursor	.mdc rules, agents, skills, commands, MCP config
GitHub Copilot	instructions, prompts, GitHub agents
Claude Code	CLAUDE.md, skills, .mcp.json
OpenCode	AGENTS.md, opencode.json
Windsurf	.windsurfrules
Amp	AGENTS.md
Codex CLI	AGENTS.md, codex.md
Gemini CLI	GEMINI.md
Cline / Roo Code	.clinerules
Aider	CONVENTIONS.md
Kiro	.kiro/steering/, .kiro/settings/mcp.json
Goose	.goosehints
Zed	.rules
Amazon Q	.amazonq/rules/, .amazonq/mcp.json

Platform is auto-detected from your git remote during hatch3r init. All board commands, agents, rules, and skills adapt to your selected platform.

How It Works

.agents/              <- Canonical source (tool-agnostic)
  ├── agents/
  ├── skills/
  ├── rules/
  ├── commands/
  ├── mcp/
  ├── AGENTS.md
  └── hatch.json       <- Manifest

.cursor/               <- Generated (Cursor adapter)
.github/               <- Generated (Copilot adapter)
CLAUDE.md              <- Generated (Claude adapter)
.windsurfrules         <- Generated (Windsurf adapter)
AGENTS.md              <- Generated (OpenCode, Amp, Codex adapters)
GEMINI.md              <- Generated (Gemini adapter)
.clinerules            <- Generated (Cline adapter)
CONVENTIONS.md         <- Generated (Aider adapter)
.kiro/                 <- Generated (Kiro adapter)
.goosehints            <- Generated (Goose adapter)
.rules                 <- Generated (Zed adapter)
.amazonq/              <- Generated (Amazon Q adapter)
.worktreeinclude       <- Generated (worktree isolation)

hatch3r keeps one source of truth in .agents/ and generates native configuration for each tool.

Multi-Repo Workspaces

hatch3r can manage multiple git repos from a single workspace root. Run hatch3r init in a non-git directory containing git subdirectories and it auto-detects the workspace layout.

my-platform/                   <- Workspace root (not a git repo)
  .agents/                     <- Shared canonical source
    workspace.json             <- Workspace manifest
    hatch.json
    agents/
    rules/
    ...
  frontend/                    <- Git repo (gets its own generated files)
    .cursor/
    CLAUDE.md
    ...
  backend/                     <- Git repo
    .cursor/
    CLAUDE.md
    ...
  infra/                       <- Git repo
    .cursor/
    CLAUDE.md
    ...

npx hatch3r init --workspace              # force workspace mode
npx hatch3r sync                          # cascade to all repos
npx hatch3r sync --repos frontend backend # sync specific repos
npx hatch3r sync --dry-run                # preview changes
npx hatch3r config                        # manage repos and sync strategy

Content flows from workspace defaults into each sub-repo with optional per-repo overrides (tools, features, include/exclude content). Sub-repos receive independent copies, not symlinks. See the Workspace guide for full details.

Workflow

hatch3r provides a full project lifecycle, from setup to release:

1. Initialize -- npx hatch3r init detects your repo and platform, asks about context and profile, generates agents/skills/rules/commands/MCP. For headless CI, pass --yes with optional flags. See agentic process diagrams.
2. Set up the board -- hatch3r-board-init creates or connects a Projects V2 board with status fields, label taxonomy, and config writeback.
3. Define work -- Create a todo.md at the project root (one item per line).
4. Fill the board -- hatch3r-board-fill parses todo.md, classifies items, groups into epics, builds a dependency DAG, and marks issues status:ready.
5. Groom the backlog -- hatch3r-board-groom surfaces stale items, priority imbalances, and decomposition candidates for selective refinement.
6. Pick up work -- hatch3r-board-pickup auto-selects the next issue by dependency order and priority, creates a branch, delegates implementation, and opens a PR.
7. Review cycle -- Reviewer + fixer agents loop (max 3 iterations) until clean, then test-writer and security-auditor run final checks.
8. Release -- hatch3r-release determines the semver bump, generates a changelog, tags, and publishes.

After init: For greenfield, run hatch3r-project-spec then hatch3r-roadmap. For brownfield, run hatch3r-codebase-map. For a single feature, run hatch3r-feature-plan. For small changes, run hatch3r-quick-change.

Commands

CLI Commands

npx hatch3r init          # Interactive setup
npx hatch3r config        # Reconfigure tools, MCP servers, features, and platform
npx hatch3r sync          # Re-generate from canonical state
npx hatch3r update        # Pull latest templates (safe merge)
npx hatch3r status        # Check sync status between canonical and generated files
npx hatch3r validate      # Validate canonical .agents/ structure
npx hatch3r verify        # Verify file integrity checksums
npx hatch3r worktree-setup <path>  # Set up gitignored files in a worktree
npx hatch3r add <pack>    # Install a community pack (coming soon)

Agent Commands

These commands are invoked inside your coding tool (e.g., as Cursor commands).

Board management: board-init, board-fill, board-groom, board-pickup, board-refresh, board-shared

Planning: project-spec, codebase-map, roadmap, feature-plan, bug-plan, refactor-plan, migration-plan, test-plan, api-spec

Workflow: workflow, quick-change, revision, debug, onboard, benchmark, hooks, learn, recipe

Operations: healthcheck, security-audit, dep-audit, release, context-health, cost-tracking

Customization: agent-customize, command-customize, skill-customize, rule-customize

All commands are prefixed with hatch3r- (e.g., hatch3r-board-fill). See the CLI Commands reference and Agent Commands reference for full details.

MCP Configuration

hatch3r init creates a .env.mcp file with required environment variables for your selected MCP servers (gitignored by default). MCP config is written to the tool-appropriate location (.cursor/mcp.json, .mcp.json, .vscode/mcp.json, etc.).

• VS Code / Copilot: Secrets load automatically via the native envFile field.
• Cursor / Claude Code / others: Source the file first: set -a && source .env.mcp && set +a && cursor .

See MCP Setup for full setup, per-server details, and PAT scope guidance.

Platform Agentic Workflows

hatch3r includes a complete board management system supporting GitHub, Azure DevOps, and GitLab. Configure in hatch.json:

{
  "board": {
    "owner": "my-org",
    "repo": "my-repo",
    "projectNumber": 1,
    "areas": ["area:frontend", "area:backend", "area:infra"]
  },
  "models": {
    "default": "opus",
    "agents": { "hatch3r-lint-fixer": "sonnet" }
  }
}

Sub-Agentic Architecture

• Four-phase pipeline -- Research, Implement, Review Loop (reviewer + fixer, max 3 iterations), Final Quality (testing + security)
• Implementer agent -- Receives a single sub-issue, delivers code + tests, reports back
• Fixer agent -- Takes reviewer findings and implements targeted fixes
• Issue workflow skill -- 8-step structured workflow with parallel sub-agent delegation for epics
• Tooling hierarchy -- Project docs > Codebase search > Library docs (Context7) > Web research

Content Profiles

During hatch3r init, you choose a content profile:

Profile	What's included	Best for
Minimal	Core agents and workflows only (core tag)	Quick setup, minimal footprint
Standard (recommended)	Full development lifecycle without niche audits	Most projects
Full	Everything including board management and all audits	Large teams, full coverage
Custom	Choose exactly what you need	Fine-grained control

Content is tagged with workflow, context, and domain tags. After init, use hatch3r config to add or remove individual content items.

Customization

hatch3r separates managed from custom files:

• hatch3r-* files are managed by hatch3r and fully replaced on update
• Files without the prefix are your customizations and are never touched
• All hatch3r-generated markdown files use managed blocks (<!-- HATCH3R:BEGIN --> / <!-- HATCH3R:END -->). Content outside these markers is preserved. Bridge files are emitted by 14 adapters: Cursor, Claude, Copilot, Cline, Codex, Gemini, Windsurf, Amp, OpenCode, Aider, Kiro, Goose, Zed, Amazon Q.

Model Selection

Configure preferred AI models per agent via hatch.json (global default and per-agent overrides), canonical agent frontmatter, or .hatch3r/agents/{id}.customize.yaml. Resolution order: customization file > manifest per-agent > agent frontmatter > manifest default.

See Model Selection for the full guide.

Cursor Plugin

hatch3r is also available as a Cursor plugin. Enable it for instant access to all rules, skills, agents, and commands without running init.

Documentation

Full documentation is available at docs.hatch3r.com.

• Vision -- Framework north-star vision and principles
• MCP Setup -- Connecting MCP servers and managing secrets
• Adapter Capability Matrix -- Per-tool support and output paths
• Agent Teams -- Multi-agent team coordination and delegation patterns
• Model Selection -- Configuring AI models per agent
• Agentic Process -- Visual diagrams of init flow, board workflow, and agent orchestration
• Troubleshooting -- Common issues and solutions
• Changelog -- Release history

License

MIT