Skip to main content

Quick Start

Get hatch3r running in your project in under a minute.

Install​

npx hatch3r init

That's it. hatch3r detects your repo, asks which tools you use, and generates everything.

What happens during init​

  1. Detects your repository -- reads git remote for owner/repo info
  2. Asks which tools -- select from Cursor, Copilot, Claude Code, OpenCode, Windsurf, Amp, Codex CLI, Gemini CLI, Cline, Aider, Kiro, Goose, Zed
  3. Asks about MCP servers -- optionally configure GitHub, Context7, Filesystem, Playwright, Brave Search
  4. Generates canonical source -- creates /.agents/ with all agents, skills, rules, and commands
  5. Generates tool configs -- adapts canonical source to native formats for each selected tool
  6. Creates .env.mcp -- secret placeholder file (gitignored) for MCP server credentials

Next steps after init​

Starting pointCommandWhat it does
New projectproject-specGenerate documentation from your project vision
Existing codebasecodebase-mapAnalyze and reverse-engineer specifications
Single featurefeature-planPlan one feature in depth
Complex bugbug-planInvestigate and plan a fix
Any projectroadmapCreate a phased roadmap from specs

After planning, the typical flow is:

board-init → todo.md → board-fill → board-pickup → review → release

See the Workflow guide for the full lifecycle.

CLI Commands​

npx hatch3r init          # Interactive setup
npx hatch3r sync          # Re-generate from canonical state
npx hatch3r update        # Pull latest templates (safe merge)
npx hatch3r status        # Check sync status
npx hatch3r validate      # Validate .agents/ structure

MCP Setup​

If you selected MCP servers during init, fill in your API keys:

# .env.mcp (generated by hatch3r init)
GITHUB_PAT=ghp_xxxxxxxxxxxx
BRAVE_API_KEY=xxxxxxxx

How secrets are loaded depends on your editor:

  • VS Code / Copilot -- Loads automatically from .env.mcp via the native envFile field
  • Cursor / Claude Code / others -- Source before launching:
set -a && source .env.mcp && set +a && cursor .

See MCP Setup for full details.