claude-code-config-kit

Generate a complete, opinionated Claude Code configuration in seconds. This CLI scaffolds .claude/ directory structure with agents, commands, hooks, skills, and the full SIRAII development pipeline.

Features

• Interactive Wizard — Answer simple questions about your project, get instant configuration.
• 4 Production Presets — SaaS, API, CLI, and Fullstack templates with sane defaults.
• 42 EJS Templates — CLAUDE.md, agents, commands, hooks, skills, and SIRAII pipeline phases.
• Smart Deduplication — Files are checksummed and skipped if unchanged, never overwritten.
• Path-Safe Generation — Validates directory paths, prevents traversal attacks, robust error handling.
• Framework Agnostic — Supports Next.js, FastAPI, Express, Go, Python, TypeScript, and custom stacks.
• SIRAII Pipeline (Optional) — 9-phase structured development workflow (security → plan → draft → audit → iterate → trace → deliver → inspect).
• MCP Server Support — Playwright, Firecrawl, and Context7 integration ready.
• Multi-Language UI — Portuguese (pt-br), English, or Spanish prompts.

Quick Start

No installation needed—run instantly with npx:

npx claude-code-config-kit

The interactive wizard will guide you through:

1. Project name and type (SaaS, API, CLI, Fullstack, or custom)
2. Technology stack selection
3. Database choice
4. Hook level (minimal, standard, or strict validation)
5. Language preferences
6. Optional providers and MCP servers
7. Output directory

All files are generated to .claude/ with zero overwrites.

Requirements

• Node.js ≥ 18.0.0
• Python ≥ 3.8 (only if SIRAII pipeline is enabled — auto-generates validation scripts)

Installation

Global (recommended)

npm install -g claude-code-config-kit
claude-code-config-kit

Local (project-scoped)

npm install --save-dev claude-code-config-kit
npx claude-code-config-kit

Instant (no installation)

npx claude-code-config-kit

Usage

Interactive Wizard

claude-code-config-kit

Walks you through every configuration option interactively.

With Preset

claude-code-config-kit --preset saas-web

Pre-fills wizard defaults from a preset (still allows overrides).

With Flags

claude-code-config-kit --preset cli-tool --output ./my-cli --yes

| Flag | Short | Description | |------|-------|-------------| | --preset <name> | -p | Pre-fill wizard with preset defaults | | --output <dir> | -o | Override output directory (default: .) | | --yes | -y | Skip final confirmation prompt | | --list-presets | — | List all available presets and exit | | --help | — | Show help message |

List Available Presets

claude-code-config-kit --list-presets

Output:

Available presets:

  saas-web             SaaS Web App (Next.js 15 + Prisma + PostgreSQL)
  api-backend          API / Backend (FastAPI + SQLAlchemy + PostgreSQL)
  cli-tool             CLI Tool (Node.js + citty + TypeScript)
  fullstack            Fullstack App (Next.js + FastAPI + Prisma + PostgreSQL)

Presets

| Preset | Stack | Database | ORM | SIRAII | Hooks | |--------|-------|----------|-----|--------|-------| | saas-web | Next.js 15 + TypeScript | PostgreSQL | Prisma | Yes | Standard | | api-backend | FastAPI + Python | PostgreSQL | SQLAlchemy | Yes | Standard | | cli-tool | Node.js + citty + TypeScript | None | — | No | Minimal | | fullstack | Next.js + FastAPI + TypeScript | PostgreSQL | Prisma | Yes | Standard |

Each preset is fully opinionated but overridable during the wizard.

What Gets Generated

Running the generator creates the following structure in your target directory:

.claude/
├── agents/
│   ├── architect.md          # Software design and architecture
│   ├── developer.md          # Implementation and coding
│   └── reviewer.md           # Code review and quality gates
├── commands/
│   ├── plan.md               # Planning and specification
│   ├── dev.md                # Local development
│   ├── test.md               # Testing and validation
│   ├── deploy.md             # Deployment and release
│   └── siraii/               # (optional) SIRAII pipeline commands
│       ├── security.md
│       ├── plan.md
│       ├── draft.md
│       ├── audit.md
│       ├── iterate.md
│       ├── trace.md
│       ├── deliver.md
│       └── full.md
├── hooks/
│   ├── hook-handler.ts       # TypeScript hook entry point
│   └── validators/
│       └── briefing_guard.py # (optional) Python validation script
├── skills/
│   └── <framework>-patterns/
│       └── SKILL.md          # Framework-specific patterns and utilities
├── briefing/
│   └── state.json            # (optional) SIRAII pipeline state
├── settings.json             # Shared Claude Code settings
└── settings.local.json       # Local overrides (git-ignored)

CLAUDE.md                      # Project-level instructions for Claude Code
.gitignore                     # Pre-configured ignore rules
.mcp.json                      # MCP server configuration (if MCP servers selected)

Key Points:

• CLAUDE.md — Central instruction file for all Claude Code interactions in your project.
• agents/ — Specialist sub-agents for architecture, development, and review.
• commands/ — Slash commands for common workflows (plan, dev, test, deploy).
• hooks/ — Pre/post tool-use validation and formatting scripts.
• skills/ — Framework-specific patterns and reusable utilities.
• SIRAII pipeline — (Optional) Full 9-phase structured development workflow.
• settings.json — Shared configuration for all Claude Code users on the project.
• settings.local.json — Personal overrides (automatically git-ignored).

Deduplication: If you run the tool again, existing files are skipped (never overwritten). To regenerate, delete specific files first.

Templates Generated

Core Files (Always)

• CLAUDE.md — Project instructions
• .claude/settings.json — Global Claude Code settings
• .claude/settings.local.json — Personal overrides
• .gitignore — Preconfigured ignore rules

Agents (Always)

• architect.md — Design and architecture decisions
• developer.md — Implementation guidelines
• reviewer.md — Code review criteria

Commands (Always)

• plan.md — Planning and specification
• dev.md — Local development workflow
• test.md — Testing strategy
• deploy.md — Deployment procedures

Hooks (Always)

• hook-handler.ts — TypeScript validation and formatting
• patterns.yaml — Hook patterns and event listeners

Skills (Always)

• <framework>-patterns/SKILL.md — Framework-specific patterns (Next.js, FastAPI, etc.)

SIRAII Pipeline (If Enabled)

• security.md — Security requirements and threat modeling
• plan.md — Detailed project planning
• draft.md — Initial implementation draft
• audit.md — Code and architecture audit
• iterate.md — Refinement and improvement
• trace.md — Traceability and dependency mapping
• deliver.md — Release and delivery procedures
• full.md — Execute entire pipeline at once
• state.json — Pipeline state and artifact tracking
• briefing_guard.py — Python validation and state guard

MCP Configuration (If Servers Selected)

• .mcp.json — MCP server definitions and configuration

Configuration Options

The wizard collects the following information:

Project Details

• Name — Kebab-case identifier (e.g., my-saas-app)
• Type — saas-web, api-backend, cli-tool, fullstack, or custom
• Stack — Framework and language (Next.js, FastAPI, Express, Go, custom, etc.)
• Database — PostgreSQL, MySQL, SQLite, MongoDB, or none

Development Setup

• Hook Level — minimal (security only), standard (security + quality), or strict (full lint + type + cost checks)
• Language — pt-br (Portuguese), en (English), or es (Spanish) for UI messages
• Providers — Anthropic (Claude), OpenAI (GPT), Google (Gemini), Ollama (local), or Azure OpenAI
• MCP Servers — Playwright (browser testing), Firecrawl (web scraping), Context7 (documentation)

Pipeline

• SIRAII — Enable full 9-phase development pipeline (recommended for complex projects)

Output

• Directory — Where to generate .claude/ (default: current directory)

Development

Build

npm run build

Compiles TypeScript to JavaScript in dist/.

Test

npm run test

Runs all tests with Vitest.

Watch Mode

npm run test:watch

Continuously runs tests as you code.

Coverage

npm run test:coverage

Generates coverage reports.

Lint

npm lint

Runs ESLint on src/.

Type Check

npm run typecheck

Validates TypeScript types without emitting code.

Development Server

npm run dev

Runs src/index.ts directly (no build step).

Architecture

Core Modules

• wizard/ — Interactive prompts and configuration collection
• generator/ — Template rendering and file writing with deduplication
• presets/ — Pre-built configuration templates
• config/ — Zod schemas for validation
• utils/ — Filesystem, Git, and logging utilities

Template Engine

Uses EJS (Embedded JavaScript) for template rendering. All templates receive the complete wizard answers as context, enabling dynamic generation based on user choices.

Validation

All inputs are validated using Zod schemas:

• Project names (kebab-case, 3–50 chars)
• Directory paths (no traversal, safe characters)
• Stack selections (enum validation)
• Provider and server lists

Examples

SaaS Web App with SIRAII

claude-code-config-kit --preset saas-web --output ./my-saas --yes

Generates a Next.js 15 + Prisma + PostgreSQL configuration with full SIRAII pipeline.

Minimal CLI Tool

claude-code-config-kit --preset cli-tool --output ./my-cli

Creates a Node.js + citty CLI configuration with minimal hooks (security only).

Custom Stack

claude-code-config-kit

Interactive mode: Choose "custom" project type, enter your framework name, select language, and build your config from scratch.

Regenerate Specific Files

rm .claude/agents/architect.md
npx claude-code-config-kit --yes

Deletes the architect agent, then regenerates only missing files.

Troubleshooting

"Invalid preset"

Ensure you're using a valid preset name. Check available presets:

claude-code-config-kit --list-presets

"Output directory validation failed"

The tool prevents path traversal attacks. Ensure your output path is safe:

claude-code-config-kit --output ./valid-dir

"No files generated"

All files already exist and haven't changed (checksummed for deduplication). To force regeneration, delete specific files first.

Files not generated in expected location

Check the final summary—it shows the exact paths generated. Confirm your --output flag or wizard selection.

Contributing

Contributions are welcome. Fork the repository, make your changes, and submit a pull request.

Development setup:

git clone https://github.com/gapaprant/claude-code-config-kit.git
cd claude-code-config-kit
npm install
npm run build
npm run test

License

MIT — see LICENSE for details.

Support

For issues, feature requests, or questions:

• GitHub Issues: gapaprant/claude-code-config-kit/issues
• Documentation: See CLAUDE.md for in-project instructions.

v0.1.0 — Production-ready configuration kit for Claude Code.