headchef

Scaffold AI IDE configs, agents, and skills for 10 code editors in one command.

npx headchef create my-project

Supported IDEs

| IDE | Key | Config | |-----|-----|--------| | Claude Code | claude | CLAUDE.md, .claude/agents/, .claude/commands/ | | OpenAI Codex | codex | .codex/config.toml | | Cursor | cursor | .cursor/rules/ | | Windsurf | windsurf | .windsurf/rules/ | | Google Antigravity | antigravity | GEMINI.md, .agent/skills/ | | GitHub Copilot | copilot | .github/copilot-instructions.md | | Cline / Roo Code | cline | .clinerules, .roo/rules/ | | JetBrains AI | jetbrains | .aiassistant/rules/ | | Augment Code | augment | .augment/rules/ | | AGENTS.md | agentsmd | AGENTS.md |

Install

# Run directly (no install)
npx headchef create my-project

# Or install globally
npm install -g headchef

Commands

headchef create [name]

Create a new project directory with AI IDE configs, agents, and project scaffolding.

headchef create my-app
headchef create my-app --framework flutter
headchef create my-app --only claude cursor
headchef create --no-brain              # skip brain integration

Interactive mode prompts for project name, IDE selection, framework, agent categories, and Obsidian brain path.

headchef init

Add AI IDE configs to an existing project.

headchef init
headchef init --framework nextjs
headchef init --only claude cursor windsurf
headchef init --target ./other-project

headchef list

Show all available IDEs, frameworks, and agent categories with counts.

Options

| Flag | Description | |------|-------------| | --only <ides...> | Generate only for specified IDEs | | --exclude <ides...> | Skip specified IDEs | | --framework <name> | Apply framework-specific rules | | --force | Overwrite existing files | | --dry-run | Preview without writing | | --no-interactive | Skip prompts, use all IDEs | | --no-brain | Skip Obsidian brain integration | | --target <dir> | Target directory (init only) |

Frameworks

| Framework | Key | Highlights | |-----------|-----|------------| | General | general | SOLID, clean code, naming, testing, security | | Flutter | flutter | Dart, BLoC, Freezed, GetIt, Firebase | | Next.js | nextjs | RSC, App Router, Shadcn UI, Zod | | React | react | Hooks, functional components, Testing Library | | Python | python | PEP 8, type hints, pytest, FastAPI |

Agents

headchef ships 55+ agents across 10 categories. Select which categories to include during setup.

| Category | Agents | Examples | |----------|--------|----------| | Core | 6 | Orchestrator, Code Reviewer, Test Writer, Bug Debugger, Architecture Planner, Docs Keeper | | Engineering | 7 | Frontend Developer, Backend Architect, AI Engineer, DevOps Automator, Mobile App Builder | | Design | 7 | UI Designer, UX Researcher, Brand Guardian, Visual Storyteller | | Marketing | 8 | Growth Hacker, Content Creator, TikTok Strategist, App Store Optimizer | | Product | 3 | Sprint Prioritizer, Trend Researcher, Feedback Synthesizer | | Project Management | 5 | Studio Producer, Project Shepherd, Senior Project Manager | | Testing | 7 | Evidence Collector, Reality Checker, Performance Benchmarker, API Tester | | Support | 6 | Support Responder, Analytics Reporter, Legal Compliance Checker | | Spatial Computing | 6 | XR Developer, Vision Pro Specialist, WebXR Engineer | | Specialized | 6 | Data Analytics Reporter, LSP Engineer, Agents Orchestrator |

Core agents are always included. Other categories are opt-in via interactive prompt.

IDEs that support discrete agent files (Claude Code, Antigravity) get one file per agent. Other IDEs get a condensed agent summary in their rules file.

Skills

15 built-in skills are generated as slash commands for Claude Code (.claude/commands/):

code-review, commit-message, unit-test, regex-generator, security-audit, accessibility-audit, architecture-design, code-converter, prompt-enhancer, diagram-generator, tech-review, sql-terminal, logic-builder, data-visualizer, domain-name-generator

Brain Integration

headchef optionally integrates with an Obsidian vault for project documentation:

• Creates a project directory in {brainPath}/Projects/Active/{project}/
• Generates an Overview.md in the brain
• Symlinks docs/ from the project to the brain directory
• Creates docs/plans/ for architecture plans
• Generates CHECKLIST.md and CHANGELOG.md

Brain path is saved to ~/.headchefrc after first entry. Use --no-brain to skip.

Generated File Structure

A typical project created with headchef create my-app (Claude + core agents):

my-app/
  CLAUDE.md              # Rules + coding standards + available agents
  CHECKLIST.md           # Task tracking
  CHANGELOG.md           # Change history
  docs/ -> brain/        # Symlink to Obsidian vault (if configured)
    plans/               # Architecture plans
  .claude/
    agents/              # One .md per agent
      headchef-orchestrator.md
      code-reviewer.md
      test-writer.md
      bug-debugger.md
      architecture-planner.md
      docs-keeper.md
    commands/            # One .md per skill
      code-review.md
      commit-message.md
      ...

Collision Handling

By default, existing files are skipped. In interactive mode, a checkbox prompt lets you pick which files to overwrite. Use --force to overwrite everything.

Preferences

headchef saves your selections to ~/.headchefrc so the next run pre-selects your previous choices.

{
  "ides": ["claude", "cursor", "windsurf"],
  "framework": "flutter",
  "agentCategories": ["core", "engineering", "testing"],
  "brainPath": "/path/to/obsidian-vault"
}

Delete ~/.headchefrc to reset. --no-interactive ignores it.

Development

git clone https://github.com/EventuallySolutions/headchef.git
cd headchef
npm install
npm run dev       # watch mode
npm test          # 207 tests
npm run build     # production build

License

MIT