Skip to content

qazuor/claude-code-config

BranchesTags

Repository files navigation

@qazuor/claude-code-config

npm version License: MIT Node.js Version TypeScript

A comprehensive CLI tool to install and manage Claude Code configurations in your projects. Configure AI agents, skills, commands, MCP servers, permissions, and template placeholders with an interactive wizard or bundle-based setup.

Table of Contents

Features

Core Capabilities

  • Interactive Wizard: Step-by-step configuration with intelligent defaults and back navigation
  • Back Navigation: Return to previous steps at any time to modify your choices
  • Auto-Detection: Automatically detects project type, package manager, and tech stack
  • 23 Bundles: Pre-grouped module sets organized by category (stacks, testing, quality, etc.)
  • Bundle Categories: Stack bundles (React+TanStack, Astro, Next.js), API bundles (Hono, Express), testing, quality, and more
  • Template Configuration: Interactive setup for {{PLACEHOLDER}} values with smart defaults
  • Standards Wizard: Configure code, testing, documentation, design, security, and performance standards
  • Pre-commit Hooks: Configurable git hooks with lint, typecheck, tests, and custom commands
  • Response Style: Configure Claude's tone, verbosity, and communication preferences
  • MCP Server Integration: Configure Model Context Protocol servers
  • Permissions System: Fine-grained control over Claude's capabilities
  • Code Style Tools: EditorConfig, Biome, Prettier, and Commitlint configuration
  • Hooks System: Notifications when Claude finishes tasks
  • Bilingual Support: Spanish and English interfaces

Modular Architecture

Category Count Description
Agents 15 Specialized AI agents for different roles (generic + specialized)
Skills 41 Reusable capabilities including framework-specific patterns
Commands 23 Slash commands for workflows
Docs 21 Reference documentation and guides
MCP Servers 27 External tool integrations
Bundles 23 Pre-grouped module sets
Standards 6 Configurable project standards (code, testing, docs, design, security, performance)

Framework-Agnostic Design

Agents are designed to be framework-agnostic and use related skills for framework-specific patterns:

  • api-engineer + hono-patterns / express-patterns / fastify-patterns / nestjs-patterns
  • database-engineer + drizzle-patterns / prisma-patterns / mongoose-patterns
  • frontend-engineer + react-patterns / nextjs-patterns / astro-patterns / tanstack-start-patterns

Intelligent Skill Selection

The wizard includes an intelligent mutual exclusivity system that:

  • Detects conflicting skills (e.g., TDD vs BDD vs ATDD)
  • Automatically disables incompatible options
  • Allows combining compatible methodologies (e.g., TDD + Clean Architecture)

Smart Defaults

  • Package Manager Detection: Automatically detects pnpm, yarn, npm, or bun
  • Script Detection: Reads package.json scripts for command defaults
  • Dependency Detection: Identifies frameworks and libraries (React, Drizzle, Zod, etc.)
  • Git Detection: Checks for git repository and GitHub remotes
  • Global Defaults: Save preferences for future projects in ~/.claude/defaults.json

What's Included

After running qazuor-claude-config init, your project will have:

.claude/
├── config.json              # Configuration storage
├── settings.json            # Claude Code settings (model, permissions)
├── settings.local.json      # Local permissions & MCP
├── agents/                  # 15 specialized AI agents
│   ├── engineering/         # Generic engineers (API, Database, Frontend)
│   ├── product/             # Product functional & technical
│   ├── quality/             # QA, debugger
│   ├── design/              # UX/UI designer
│   └── specialized/         # SEO, i18n, content, tech writer
├── skills/                  # 41 development skills
│   ├── testing/             # TDD, security, performance, QA
│   ├── patterns/            # Architecture patterns (Clean, Hexagonal, etc.)
│   ├── api-frameworks/      # Hono, Express, Fastify, NestJS patterns
│   ├── database/            # Drizzle, Prisma, Mongoose patterns
│   ├── frontend-frameworks/ # React, Next.js, Astro, TanStack patterns
│   ├── development/         # Git, Vercel, Shadcn, diagrams
│   └── design/              # Brand, errors, markdown, PDF
├── commands/                # 23 slash commands
│   ├── audit/               # Security, performance, accessibility
│   ├── planning/            # Feature planning, sync, cleanup
│   ├── git/                 # Commit helper
│   ├── meta/                # Create agent/command/skill, help
│   └── formatting/          # Markdown formatter
├── docs/                    # 21 documentation files
│   ├── workflows/           # Decision tree, phases, protocols
│   ├── standards/           # Code, testing, docs standards
│   └── templates/           # PDR, tech analysis, TODOs
├── schemas/                 # JSON schemas (optional)
├── scripts/                 # Utility scripts (optional)
├── hooks/                   # Notification hooks (optional)
└── sessions/                # Planning sessions (optional)
    └── planning/
CLAUDE.md                    # Main Claude instructions

Installation

Global Installation (Recommended)

# Using pnpm (recommended)
pnpm add -g @qazuor/claude-code-config

# Using npm
npm install -g @qazuor/claude-code-config

# Using yarn
yarn global add @qazuor/claude-code-config

# Using bun
bun add -g @qazuor/claude-code-config

Using npx (No Installation)

npx @qazuor/claude-code-config init

Local Development

git clone https://github.com/qazuor/claude-code-config.git
cd claude-code-config
pnpm install
pnpm build
pnpm link --global

Quick Start

Interactive Setup (Recommended)

# Initialize in current directory
qazuor-claude-config init

# Initialize in specific directory
qazuor-claude-config init ./my-project

The wizard will guide you through:

  1. Project Information - Name, description, organization, entity types
  2. Preferences - Language, co-author settings
  3. Scaffold Options - Claude-only or full project structure
  4. Module Selection - Choose bundles or custom modules (with smart skill selection)
  5. Hook Configuration - Desktop/audio notifications
  6. MCP Servers - External tool integrations
  7. Permissions - What Claude can do
  8. Code Style - EditorConfig, Biome, Prettier, Commitlint
  9. CI/CD - GitHub Actions workflows
  10. Folder Preferences - Test, planning, docs locations
  11. Template Configuration - Auto-detected command/path/target values
  12. Claude Settings - Model, API choice, permissions, behavior

Tip: You can go back to any previous step using the "← Back" option to modify your choices.

Bundle-based Setup

# Quick setup with specific bundles
qazuor-claude-config init --bundles react-tanstack-stack,testing-complete

# Skip all prompts with defaults
qazuor-claude-config init --bundles hono-drizzle-stack --yes

# Preview what would be created
qazuor-claude-config init --bundles astro-react-stack --dry-run

Post-Installation Configuration

# Reconfigure template placeholders
qazuor-claude-config configure

# Scan for unconfigured placeholders
qazuor-claude-config configure --scan

# Preview changes without applying
qazuor-claude-config configure --preview

Commands

init [path]

Initialize Claude configuration in a project.

qazuor-claude-config init [options] [path]

Options

Option Description
-b, --bundles <ids> Comma-separated bundle IDs (e.g., react-tanstack-stack,testing-complete)
-t, --template <url> Remote git repository URL for custom templates
--branch <name> Branch or tag for remote template (default: main)
-y, --yes Accept all defaults, skip interactive prompts
-f, --force Overwrite existing configuration
--dry-run Show what would be created without making changes
--claude-only Only create Claude config, skip project scaffolding
--no-placeholders Skip placeholder replacement
--no-mcp Skip MCP server configuration
-v, --verbose Show detailed output

Examples

# Full interactive setup
qazuor-claude-config init

# Quick setup with bundles
qazuor-claude-config init --bundles react-tanstack-stack,testing-complete --yes

# From custom template repository
qazuor-claude-config init --template https://github.com/your-org/claude-templates --branch v2.0

# Force overwrite existing
qazuor-claude-config init --bundles hono-drizzle-stack --force

configure

Configure or reconfigure template placeholders interactively.

qazuor-claude-config configure [options] [path]

Options

Option Description
--scan Scan for unconfigured placeholders only
-c, --category <name> Configure specific category: commands, paths, targets, tracking, techStack, environment, brand
--preview Preview changes without applying
--show-defaults Show global defaults stored in ~/.claude/defaults.json
-v, --verbose Show detailed output

Examples

# Interactive configuration
qazuor-claude-config configure

# Scan for unconfigured placeholders
qazuor-claude-config configure --scan

# Configure only commands
qazuor-claude-config configure --category commands

# Preview what would be replaced
qazuor-claude-config configure --preview

# Show global defaults
qazuor-claude-config configure --show-defaults

standards

Configure project standards interactively. This wizard helps you define code style, testing, documentation, design, security, and performance standards for your project.

qazuor-claude-config standards [options] [path]

Options

Option Description
--scan Scan for unconfigured standard placeholders only
-c, --category <name> Configure specific category: code, testing, documentation, design, security, performance
--preview Preview changes without applying
--update-templates Update/sync templates from package to project (for existing installations)
-y, --yes Accept defaults without prompts
-v, --verbose Show detailed output

Categories

Category Configures
code Indent style, quotes, semicolons, max lines, TypeScript rules
testing Coverage target, TDD, test patterns, test location
documentation JSDoc level, examples, changelog format, comments
design CSS framework, component library, accessibility, dark mode
security Auth pattern, validation library, CSRF, rate limiting
performance Core Web Vitals (LCP, FID, CLS), bundle size, API response time

Examples

# Full interactive standards wizard
qazuor-claude-config standards

# Configure only code standards
qazuor-claude-config standards --category code

# Scan for unconfigured placeholders
qazuor-claude-config standards --scan

# Preview changes without applying
qazuor-claude-config standards --preview

# Update templates from package (for existing installations)
qazuor-claude-config standards --update-templates

# Accept all defaults
qazuor-claude-config standards --yes

list [type]

List available modules, bundles, or MCP servers.

qazuor-claude-config list [options] [type]

Types

Type Description
agents List all 15 available agents
skills List all 41 available skills
commands List all 23 available commands
docs List all 21 documentation modules
bundles List all 23 module bundles
mcp List all 27 MCP servers
(none) List summary of all modules

Options

Option Description
-v, --verbose Show detailed information
-j, --json Output as JSON

Examples

# List all modules summary
qazuor-claude-config list

# List agents with details
qazuor-claude-config list agents --verbose

# List bundles
qazuor-claude-config list bundles

# Export as JSON
qazuor-claude-config list agents --json > agents.json

add <module>

Add a module to the configuration.

qazuor-claude-config add [options] <module>

Module Format

<category>:<module-id>

Categories: agent, skill, command, doc

Examples

# Add an agent
qazuor-claude-config add agent:tech-lead
qazuor-claude-config add agent:api-engineer

# Add a skill
qazuor-claude-config add skill:tdd-methodology
qazuor-claude-config add skill:hono-patterns

# Add a command
qazuor-claude-config add command:security-audit

# Force overwrite
qazuor-claude-config add agent:qa-engineer --force

remove <module>

Remove a module from the configuration.

qazuor-claude-config remove [options] <module>

Examples

# Remove an agent
qazuor-claude-config remove agent:tech-lead

# Remove without confirmation
qazuor-claude-config remove skill:tdd-methodology --force

status

Show current Claude configuration status.

qazuor-claude-config status [options]

Options

Option Description
-v, --verbose Show detailed configuration
-j, --json Output as JSON
--path <path> Project path (default: current directory)

update

Update configuration and modules.

qazuor-claude-config update [options]

Options

Option Description
--check Check for updates without applying
--modules Update only modules
--config Re-run configuration prompts
--all Update everything
-f, --force Overwrite local changes
-i, --interactive Ask about each change

Bundles

Bundles are pre-grouped modules for specific use cases. Select them during init with --bundles or add interactively. The CLI includes 23 bundles organized by category.

Stack Bundles

Complete technology stacks for different project types.

Bundle Description Tech Stack
react-tanstack-stack React + TanStack for SPAs/admin dashboards React, TanStack Start/Router/Query, TypeScript
astro-react-stack Astro + React for content sites Astro, React, Tailwind CSS, MDX
nextjs-prisma-stack Full-stack Next.js with Prisma Next.js, React, Prisma, Tailwind CSS
express-prisma-stack Express API with Prisma ORM Express.js, Prisma, PostgreSQL, Zod
hono-drizzle-stack Hono API with Drizzle ORM Hono, Drizzle ORM, PostgreSQL, Zod

Testing Bundles

Bundle Description Includes
testing-complete Full testing suite (TDD, E2E, performance, QA) qa-engineer, tdd-methodology, web-app-testing, api-app-testing, performance-testing, qa-criteria-validator
testing-minimal Essential testing tools tdd-methodology, api-app-testing, run-tests

Quality Bundles

Bundle Description Includes
quality-complete Full QA with security/performance/accessibility audits qa-engineer, debugger, security-audit, performance-audit, accessibility-audit, review commands
quality-minimal Essential quality checks quality-check, code-check, review-code

Database Bundles

Bundle Description Includes
drizzle-database Drizzle ORM patterns database-engineer, drizzle-patterns, json-data-auditor
prisma-database Prisma ORM patterns database-engineer, prisma-patterns, json-data-auditor
mongoose-database MongoDB + Mongoose database-engineer, mongoose-patterns, json-data-auditor

API Bundles

Bundle Description Includes
hono-api Hono framework api-engineer, hono-patterns, api-app-testing, error-handling-patterns
express-api Express.js framework api-engineer, express-patterns, api-app-testing, error-handling-patterns
fastify-api Fastify framework api-engineer, fastify-patterns, api-app-testing, error-handling-patterns
nestjs-api NestJS framework api-engineer, nestjs-patterns, api-app-testing, error-handling-patterns

Frontend Bundles

Bundle Description Includes
react-ui React + Shadcn UI frontend-engineer, react-patterns, ux-ui-designer, shadcn-specialist, brand-guidelines, accessibility-audit
react-forms React Hook Form + Zod frontend-engineer, react-patterns, react-hook-form-patterns, shadcn-specialist
react-state-zustand Zustand state management frontend-engineer, react-patterns, zustand-patterns, tanstack-query-patterns
react-state-redux Redux Toolkit frontend-engineer, react-patterns, redux-toolkit-patterns
nextjs-auth NextAuth.js authentication frontend-engineer, nextjs-patterns, nextauth-patterns, security-testing
nextjs-i18n Next.js internationalization frontend-engineer, nextjs-patterns, i18n-specialist, i18n-patterns

Workflow Bundles

Bundle Description Includes
planning-complete Full planning workflow (PDR, tech analysis, tasks) product-functional, product-technical, tech-lead, planning commands, templates
documentation-complete Documentation tools tech-writer, mermaid-diagram-specialist, update-docs, documentation-standards
git-workflow Git commit conventions git-commit-helper, commit command
cicd-github-actions GitHub Actions CI/CD github-actions-specialist, cicd-workflows

Modules

Agents (15 Available)

Specialized AI agents for different development roles. Engineering agents are framework-agnostic and use related skills for framework-specific patterns.

Engineering Agents

ID Name Description Related Skills
tech-lead Tech Lead Architecture, coordination, code review -
api-engineer API Engineer Generic backend API development hono, express, fastify, nestjs patterns
database-engineer Database Engineer Generic database design and development drizzle, prisma, mongoose patterns
frontend-engineer Frontend Engineer Generic frontend development react, nextjs, astro, tanstack patterns
node-typescript-engineer Node/TS Engineer Node.js/TypeScript development -

Product Agents

ID Name Description
product-functional Product Functional PDR and user requirements
product-technical Product Technical Technical analysis and task breakdown

Quality Agents

ID Name Description
qa-engineer QA Engineer Testing and quality assurance
debugger Debugger Bug investigation and fixing

Design Agents

ID Name Description
ux-ui-designer UX/UI Designer UI/UX design and implementation

Specialized Agents

ID Name Description
tech-writer Tech Writer Technical documentation
seo-ai-specialist SEO Specialist SEO optimization
i18n-specialist i18n Specialist Internationalization
content-writer Content Writer Web copywriting
enrichment-agent Enrichment Agent Data enrichment and planning context

Skills (41 Available)

Reusable capabilities that can be invoked by agents. Skills are organized by category and some have mutual exclusivity constraints.

Framework-Specific Skills

API Frameworks (use with api-engineer):

ID Name Description
hono-patterns Hono Patterns Hono framework patterns and best practices
express-patterns Express Patterns Express.js patterns and middleware
fastify-patterns Fastify Patterns Fastify plugins and hooks
nestjs-patterns NestJS Patterns NestJS modules, controllers, providers

Database ORMs (use with database-engineer):

ID Name Description
drizzle-patterns Drizzle Patterns Drizzle ORM schemas and queries
prisma-patterns Prisma Patterns Prisma client and migrations
mongoose-patterns Mongoose Patterns Mongoose schemas and models

Frontend Frameworks (use with frontend-engineer):

ID Name Description
react-patterns React Patterns React hooks, components, state
nextjs-patterns Next.js Patterns Next.js App Router, SSR, SSG
astro-patterns Astro Patterns Astro islands, content collections
tanstack-start-patterns TanStack Start TanStack Router and Query patterns

Methodology Skills

Development Methodologies (mutually exclusive - pick one):

ID Name Description
tdd-methodology TDD Methodology Test-driven development (Red-Green-Refactor)
bdd-methodology BDD Methodology Behavior-driven development with Gherkin
atdd-methodology ATDD Methodology Acceptance test-driven development

Architectural Methodologies (can combine with development methodologies):

ID Name Description
clean-architecture Clean Architecture Concentric layers with dependency inversion
hexagonal-architecture Hexagonal Architecture Ports and Adapters pattern
vertical-slice-architecture Vertical Slice Feature-based code organization

Note: Clean and Hexagonal are alternatives (similar approaches). Vertical Slice is an alternative to both layered architectures.

Testing Skills

ID Name Description
security-testing Security Testing Security vulnerability testing
performance-testing Performance Testing Performance optimization
api-app-testing API Testing API testing strategies
web-app-testing Web App Testing Web application testing
qa-criteria-validator QA Validator Quality criteria validation

Development Skills

ID Name Description
git-commit-helper Git Commit Commit message formatting
vercel-specialist Vercel Vercel deployment
shadcn-specialist Shadcn Shadcn UI components
mermaid-diagram-specialist Mermaid Diagram generation
add-memory Add Memory Context memory

Design Skills

ID Name Description
brand-guidelines Brand Guidelines Brand consistency
error-handling-patterns Error Handling Error patterns
markdown-formatter Markdown Markdown formatting
pdf-creator-editor PDF Editor PDF manipulation
json-data-auditor JSON Auditor JSON validation

Commands (23 Available)

Slash commands for common workflows.

Quality Commands

Command Description
/quality-check Comprehensive quality validation
/code-check Lint + typecheck
/run-tests Execute test suites

Audit Commands

Command Description
/security-audit OWASP security audit
/performance-audit Performance analysis
/accessibility-audit WCAG compliance audit

Planning Commands

Command Description
/start-feature-plan Initialize feature planning
/start-refactor-plan Plan refactoring
/sync-planning Sync to issue tracker
/sync-planning-github Sync to GitHub Issues
/sync-todos-github Sync TODOs to GitHub
/check-completed-tasks Auto-detect completed tasks
/planning-cleanup Clean up planning artifacts
/cleanup-issues Clean up stale issues

Development Commands

Command Description
/add-new-entity Scaffold new entity
/update-docs Update documentation
/five-why Root cause analysis

Git Commands

Command Description
/commit Generate atomic commit

Meta Commands

Command Description
/create-agent Create new agent
/create-command Create new command
/create-skill Create new skill
/help Show help information

Formatting Commands

Command Description
/format-markdown Format markdown files

Documentation (20 Available)

Reference documentation and workflow guides.

ID Description
quick-start Quick start guide
decision-tree Workflow decision guide
quick-fix-protocol Level 1 quick fix workflow
atomic-task-protocol Level 2 atomic task workflow
phase-1-planning Planning phase guide
phase-2-implementation Implementation guide
phase-3-validation Validation guide
phase-4-finalization Finalization guide
code-standards Coding standards (configurable)
testing-standards Testing guidelines (configurable)
documentation-standards Documentation guidelines (configurable)
design-standards Design system standards (configurable)
security-standards Security standards (configurable)
performance-standards Performance standards (configurable)
architecture-patterns Architecture patterns
pdr-template Product Definition Report template
tech-analysis-template Technical analysis template
todos-template Task breakdown template
workflow-diagrams Mermaid diagrams
glossary Project terminology
mcp-servers MCP documentation

Template Configuration

The CLI can auto-configure {{PLACEHOLDER}} values in templates by detecting your project setup.

Configuration Categories

Category Examples
Commands {{TYPECHECK_COMMAND}}, {{LINT_COMMAND}}, {{TEST_COMMAND}}, {{COVERAGE_COMMAND}}
Paths {{PLANNING_PATH}}, {{ARCHIVE_PATH}}, {{SCHEMAS_PATH}}
Targets {{COVERAGE_TARGET}}, {{BUNDLE_SIZE_TARGET}}, {{LCP_TARGET}}
Tracking {{ISSUE_TRACKER}}, {{TRACKING_FILE}}, {{TASK_CODE_PATTERN}}
Tech Stack {{FRONTEND_FRAMEWORK}}, {{DATABASE_ORM}}, {{VALIDATION_LIBRARY}}
Environment {{GITHUB_TOKEN_ENV}}, {{GITHUB_OWNER_ENV}}
Brand {{BRAND_NAME}}, {{PRIMARY_COLOR}}, {{TONE_OF_VOICE}}

Auto-Detection

The CLI automatically detects values from:

  • package.json scripts: typecheck, lint, test, coverage, build
  • Dependencies: React, Next.js, Drizzle, Prisma, Zod, Vitest, Jest
  • Lock files: pnpm-lock.yaml, yarn.lock, package-lock.json, bun.lockb
  • Config files: tsconfig.json, .git directory

Global Defaults

Save configuration as defaults for future projects:

# During init, you'll be asked:
# "Save these values as global defaults for future projects?"

# View saved defaults
qazuor-claude-config configure --show-defaults

Defaults are stored in ~/.claude/defaults.json.

Standards Configuration

The standards wizard (qazuor-claude-config standards) allows you to configure project-wide standards that are automatically applied to documentation templates.

Standard Categories

Code Standards

Setting Options Default
Indent Style space, tab space
Indent Size 2, 4 2
Max Line Length 80, 100, 120 100
Max File Lines 300, 500, 800, 1000 500
Quote Style single, double single
Semicolons true, false true
Trailing Commas all, es5, none all
Allow any Type true, false false
Named Exports Only true, false true
RO-RO Pattern true, false true
JSDoc Required true, false true

Testing Standards

Setting Options Default
Coverage Target 60%, 70%, 80%, 90%, 95% 90%
TDD Required true, false true
Test Pattern aaa (Arrange-Act-Assert), gwt (Given-When-Then) aaa
Test Location separate (test/ folder), colocated (tests) separate
Unit Test Max 50ms, 100ms, 200ms 100ms
Integration Test Max 500ms, 1000ms, 2000ms 1000ms

Documentation Standards

Setting Options Default
JSDoc Level minimal, standard, comprehensive standard
Require Examples true, false true
Changelog Format conventional, keepachangelog conventional
Inline Comment Policy why-not-what, minimal, extensive why-not-what

Design Standards

Setting Options Default
CSS Framework tailwind, css-modules, styled-components, vanilla tailwind
Component Library shadcn, radix, headless, none shadcn
Accessibility Level A, AA, AAA AA
Dark Mode Support true, false true

Security Standards

Setting Options Default
Auth Pattern jwt, session, oauth, none jwt
Input Validation zod, yup, joi, manual zod
CSRF Protection true, false true
Rate Limiting true, false true

Performance Standards

Setting Options Default
LCP Target 1500ms, 2000ms, 2500ms, 4000ms 2500ms
FID Target 50ms, 100ms, 200ms, 300ms 100ms
CLS Target 0.05, 0.1, 0.15, 0.25 0.1
Bundle Size Target 100KB, 150KB, 250KB, 500KB 250KB
API Response Target 100ms, 200ms, 300ms, 500ms 200ms

Presets

Preset Description
strict High coverage (95%), strict TypeScript, comprehensive docs
balanced Standard settings for most projects (default)
relaxed Lower coverage (70%), more flexible rules
startup Fast iteration, minimal overhead
enterprise Maximum standards, full documentation

Pre-commit Hooks

Configurable pre-commit hooks powered by Husky. The wizard generates sophisticated bash scripts based on your configuration.

Configuration Options

Option Description Default
enabled Enable/disable pre-commit hook true
lint.enabled Run linting true
lint.stagedOnly Only lint staged files true
lint.tool Linting tool (biome, eslint, custom) biome
typecheck.enabled Run TypeScript type checking true
tests.enabled Run tests true
tests.mode Test mode (none, affected, all) affected
tests.coverageThreshold Minimum coverage (0 = disabled) 0
formatCheck.enabled Check formatting false
formatCheck.tool Format tool (biome, prettier, custom) biome
showTiming Show execution time for each step true
continueOnFailure Run all checks even if one fails false

Custom Commands

Add custom validation commands:

{
  "customCommands": [
    {
      "name": "Security Scan",
      "command": "pnpm audit --audit-level=high",
      "allowFailure": true,
      "order": 50
    }
  ]
}

Presets

Preset Description
minimal Lint only (staged files)
standard Lint + typecheck (default)
strict Lint + typecheck + affected tests

Generated Hook Example

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# Pre-commit hook - Generated by @qazuor/claude-code-config
echo "🔍 Running pre-commit checks..."

# Linting
echo ""
echo "📝 Linting..."
step_start
pnpm biome check --staged --no-errors-on-unmatched || { echo "  ❌ Lint failed"; exit 1; }
echo "  ✅ Lint passed"
step_end

# Type checking
echo ""
echo "🔷 Type checking..."
step_start
pnpm typecheck || { echo "  ❌ Type check failed"; exit 1; }
echo "  ✅ Types OK"
step_end

echo ""
echo "✨ All checks passed!"

Response Style

Configure Claude's communication style and tone for your project.

Configuration Options

Option Description Options
tone Overall response tone friendly, professional, formal, strict, mentor
verbosity Level of detail in responses concise, balanced, detailed
responseLanguage Language for responses (code always in English) en, es, auto
useEmojis Use emojis in responses true, false
errorStyle How to report errors supportive, neutral, direct
explainReasoning Include explanation of "why" true, false
offerAlternatives Suggest multiple solutions true, false
proactivity Level of unsolicited suggestions minimal, moderate, high
confirmBeforeBigChanges Ask before major changes true, false

Tone Options

Tone Description
friendly Casual, approachable, occasional emojis
professional Professional but accessible
formal Formal, technical language
strict Direct, no-nonsense, to the point
mentor Educational, explains the "why"

Presets

Preset Tone Verbosity Emojis Error Style
friendly friendly balanced ✓ supportive
professional professional balanced ✗ neutral
strict strict concise ✗ direct
mentor mentor detailed ✗ supportive

Generated Guidelines

The configuration generates guidelines in CLAUDE.md:

## Response Style

**Tone:** Professional
**Verbosity:** Balanced
**Language:** Spanish (code in English)
**Emojis:** No
**Error Style:** Neutral
**Explain Reasoning:** Yes
**Offer Alternatives:** Yes
**Proactivity:** Moderate
**Confirm Big Changes:** Yes

### Guidelines
- Respond in Spanish, write code/comments in English
- Be professional but accessible
- Explain the "why" behind decisions
- Present alternatives when multiple valid approaches exist
- Ask for confirmation before architectural changes

MCP Servers

Model Context Protocol servers extend Claude's capabilities. All 27 servers are verified npm packages.

By Category

Documentation & Search

ID Name Requires Config
context7 Context7 No
brave-search Brave Search Yes (BRAVE_API_KEY)
perplexity Perplexity Yes (PERPLEXITY_API_KEY)

Database & Cache

ID Name Requires Config
postgres PostgreSQL Yes (DATABASE_URL)
neon Neon Yes (NEON_API_KEY)
mysql MySQL Yes (MYSQL_URL)
redis Redis Yes (REDIS_URL)

Version Control

ID Name Requires Config
github GitHub Yes (GITHUB_TOKEN)
gitlab GitLab Yes (GITLAB_TOKEN)
git Git No

Deployment & Infrastructure

ID Name Requires Config
vercel Vercel Yes (VERCEL_TOKEN)
cloudflare Cloudflare Yes (CLOUDFLARE_TOKEN)
docker Docker No
aws-kb-retrieval AWS KB Yes (AWS_ACCESS_KEY_ID)

Testing & Debugging

ID Name Requires Config
playwright Playwright No
chrome-devtools Chrome DevTools No

Communication & Project Management

ID Name Requires Config
slack Slack Yes (SLACK_TOKEN)
linear Linear Yes (LINEAR_API_KEY)
notion Notion Yes (NOTION_TOKEN)

Payments

ID Name Requires Config
stripe Stripe Yes (STRIPE_API_KEY)
mercadopago Mercado Pago Yes (MP_ACCESS_TOKEN)

Design & UI

ID Name Requires Config
figma Figma Yes (FIGMA_TOKEN)
shadcn Shadcn UI No
magic-ui Magic UI No

Other

ID Name Requires Config
sentry Sentry Yes (SENTRY_AUTH_TOKEN)
obsidian Obsidian No
n8n n8n Yes (N8N_API_KEY)
sequential-thinking Sequential Thinking No

Configuration Levels

  • User level: ~/.claude/settings.json - Available in all projects
  • Project level: .claude/settings.local.json - Project-specific
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@anthropic/claude-code-mcp-context7"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Permissions

Control what Claude can do in your project.

Presets

Preset Description
default Safe defaults - read all, write code/config, no git push
trust Full trust - all operations allowed except push
restrictive Read-only mode - minimal write permissions

Permission Categories

File Operations

Permission Default Trust Restrictive
Read any file ✓ ✓ ✓
Write code (.ts, .js, .tsx) ✓ ✓ ✗
Write config (.json, .yaml) ✓ ✓ ✗
Write markdown (.md) ✓ ✓ ✗
Write other files ✗ ✓ ✗

Git Operations

Permission Default Trust Restrictive
status, diff, log ✓ ✓ ✓
add (staging) ✗ ✓ ✗
commit ✗ ✓ ✗
push ✗ ✗ ✗
checkout, branch ✗ ✓ ✗

Bash Operations

Permission Default Trust Restrictive
Package manager ✓ ✓ ✗
Testing commands ✓ ✓ ✗
Build commands ✓ ✓ ✗
Docker commands ✗ ✓ ✗
Arbitrary commands ✗ ✓ ✗

Code Style

Configure code style tools during initialization.

Available Tools

Tool Description
EditorConfig Editor-agnostic formatting rules
Biome Fast linter and formatter
Prettier Opinionated code formatter
Commitlint Commit message linting

EditorConfig Options

  • Indent style (tabs/spaces)
  • Indent size
  • Line endings (LF/CRLF)
  • Final newline
  • Trim trailing whitespace
  • Max line length

Biome Options

  • Formatter settings (indent, quotes, semicolons)
  • Linter rules (recommended, correctness, security)
  • Import organization
  • Ignore patterns

Prettier Options

  • Print width
  • Tab width
  • Semicolons
  • Quote style
  • Trailing commas
  • Bracket spacing

Commitlint Options

  • Commit types allowed
  • Scope requirements
  • Header max length
  • Body requirements
  • Husky integration

Hooks

Notification hooks alert you when Claude finishes tasks.

Available Hooks

Hook Trigger Description
notification Task completion Desktop/audio notifications
stop Claude stops Beep or custom sound
subagentStop Subagent completes Background task notifications

Configuration

{
  "hooks": {
    "enabled": true,
    "notification": {
      "desktop": true,
      "audio": true,
      "customCommand": "notify-send 'Claude' '$MESSAGE'"
    },
    "stop": {
      "beep": true,
      "customSound": "/path/to/sound.wav"
    }
  }
}

System Requirements

Feature Linux macOS Windows
Desktop notifications libnotify-bin Built-in Built-in
Audio (TTS) Piper TTS say SAPI
Audio (beep) aplay afplay PowerShell

Project Structure

your-project/
├── .claude/
│   ├── config.json              # Claude Code Config settings
│   ├── settings.local.json      # Local permissions & MCP
│   ├── agents/                  # AI agent definitions
│   │   ├── engineering/
│   │   ├── product/
│   │   ├── quality/
│   │   ├── design/
│   │   └── specialized/
│   ├── skills/                  # Skill definitions
│   │   ├── testing/
│   │   ├── development/
│   │   └── design/
│   ├── commands/                # Slash commands
│   │   ├── audit/
│   │   ├── planning/
│   │   ├── git/
│   │   ├── meta/
│   │   └── formatting/
│   ├── docs/                    # Documentation
│   │   ├── workflows/
│   │   ├── standards/
│   │   └── templates/
│   ├── schemas/                 # JSON schemas (optional)
│   ├── scripts/                 # Utility scripts (optional)
│   ├── hooks/                   # Hook scripts (optional)
│   └── sessions/                # Planning sessions (optional)
│       └── planning/
├── CLAUDE.md                    # Main Claude instructions
└── .editorconfig               # EditorConfig (optional)

Placeholders

Templates use two types of placeholders:

Project Placeholders (Replaced During Init)

Placeholder Description
[Project Name] Project name
your-org GitHub organization
your-repo Repository name
example.com Project domain
entity Primary entity type

Template Placeholders (Configured via configure)

Placeholder Example Value
{{TYPECHECK_COMMAND}} pnpm typecheck
{{LINT_COMMAND}} pnpm lint
{{TEST_COMMAND}} pnpm test
{{COVERAGE_TARGET}} 90
{{ISSUE_TRACKER}} github
{{DATABASE_ORM}} Drizzle

Programmatic API

Use the library programmatically in Node.js applications.

Installation

npm install @qazuor/claude-code-config

Usage

import {
  // Configuration
  readConfig,
  writeConfig,
  hasConfig,
  createDefaultConfig,

  // Modules
  loadRegistry,
  resolveModules,
  installModules,

  // Detection
  detectProject,

  // Placeholders
  replacePlaceholders,

  // Templates
  processTemplates,
  buildTemplateContext,

  // Bundles
  resolveBundles,
  resolveBundle,
  mergeBundleSelection,
  BUNDLES,
  getAllBundles,
  getBundleById,

  // Constants
  MCP_SERVERS,
  DEPENDENCIES,
  PLACEHOLDERS,
  PERMISSION_PRESETS,
} from '@qazuor/claude-code-config';

// Detect project type
const detection = await detectProject('./my-project');
console.log(detection.projectType);      // 'nextjs', 'astro', 'hono', etc.
console.log(detection.packageManager);   // 'pnpm', 'npm', 'yarn', 'bun'

// Resolve bundles to module selections
const bundleResult = resolveBundles(['react-tanstack-stack', 'testing-complete']);
console.log(bundleResult.agents);    // ['react-senior-dev', 'tanstack-start-engineer', ...]
console.log(bundleResult.skills);    // ['web-app-testing', 'tdd-methodology', ...]

// Read/write configuration
const config = await readConfig('./my-project');
await writeConfig('./my-project', config);

Types

import type {
  // Configuration
  ClaudeConfig,
  ModuleSelection,
  HookConfig,
  TemplateSource,
  Preferences,
  ScaffoldConfig,
  Customizations,

  // Modules
  ModuleRegistry,
  ModuleDefinition,
  ModuleCategory,
  ResolvedModule,

  // Bundles
  BundleCategory,
  BundleDefinition,
  BundleSelectionResult,
  ResolvedBundle,

  // Scaffold & Detection
  ScaffoldType,
  ProjectType,
  ScaffoldOptions,
  ScaffoldResult,
  ProjectDetectionResult,

  // Templates
  TemplateContext,
  TemplateResult,
  TemplateProcessingReport,

  // MCP & Permissions
  McpServerDefinition,
  McpCategory,
  McpConfigField,
  McpInstallation,
  PermissionPreset,
  PermissionsConfig,
} from '@qazuor/claude-code-config';

Configuration File

The main configuration is stored in .claude/qazuor-claude-config.json.

{
  "version": "0.1.0",
  "templateSource": {
    "type": "local",
    "installedAt": "2024-01-15T10:30:00.000Z"
  },
  "project": {
    "name": "my-project",
    "description": "My awesome project",
    "org": "myorg",
    "repo": "my-project",
    "entityType": "product",
    "entityTypePlural": "products"
  },
  "preferences": {
    "language": "en",
    "responseLanguage": "en",
    "includeCoAuthor": true
  },
  "mcp": {
    "level": "project",
    "servers": [
      { "serverId": "context7", "level": "project" }
    ]
  },
  "modules": {
    "agents": { "selected": ["tech-lead", "qa-engineer"], "excluded": [] },
    "skills": { "selected": ["tdd-methodology"], "excluded": [] },
    "commands": { "selected": ["quality-check", "commit"], "excluded": [] },
    "docs": { "selected": ["quick-start"], "excluded": [] }
  },
  "extras": {
    "schemas": true,
    "scripts": false,
    "hooks": { "enabled": true, "notification": { "desktop": true } },
    "sessions": true,
    "codeStyle": { "enabled": true, "biome": true }
  },
  "templateConfig": {
    "commands": {
      "typecheck": "pnpm typecheck",
      "lint": "pnpm lint",
      "test": "pnpm test"
    },
    "targets": {
      "coverageTarget": 90
    },
    "tracking": {
      "issueTracker": "github"
    },
    "techStack": {
      "frontendFramework": "React",
      "databaseOrm": "Drizzle",
      "validationLibrary": "Zod"
    }
  }
}

Custom Templates

Using Remote Templates

# Use templates from custom repository
qazuor-claude-config init --template https://github.com/your-org/claude-templates

# Specify branch or tag
qazuor-claude-config init --template https://github.com/your-org/claude-templates --branch v2.0

Template Structure

your-templates/
├── agents/
│   ├── _registry.json
│   ├── engineering/
│   │   └── *.md
│   └── quality/
│       └── *.md
├── skills/
│   ├── _registry.json
│   └── *.md
├── commands/
│   ├── _registry.json
│   └── *.md
├── docs/
│   ├── _registry.json
│   └── *.md
├── schemas/
│   └── *.json
├── scripts/
│   └── *.sh
└── hooks/
    └── *.sh

Registry Format

{
  "category": "agents",
  "modules": [
    {
      "id": "my-agent",
      "name": "My Agent",
      "description": "Description of my agent",
      "file": "engineering/my-agent.md",
      "tags": ["engineering", "custom"],
      "longDescription": "Extended description...",
      "whatItDoes": ["Action 1", "Action 2"],
      "whenToUse": "When to use this agent",
      "skillLevel": "intermediate",
      "relatedModules": ["other-agent"]
    }
  ]
}

Requirements

  • Node.js: >= 18.0.0
  • Package Manager: pnpm, npm, yarn, or bun
  • Git: For version control operations

Optional Dependencies

Dependency Purpose Installation
libnotify-bin Desktop notifications (Linux) apt install libnotify-bin
piper-tts Audio notifications pip install piper-tts
jq JSON processing in hooks apt install jq

Contributing

Contributions are welcome! Please follow these guidelines:

Development Setup

# Clone repository
git clone https://github.com/qazuor/claude-code-config.git
cd claude-code-config

# Install dependencies
pnpm install

# Development mode (watch)
pnpm dev

# Build
pnpm build

# Run linter
pnpm lint

# Fix linting issues
pnpm lint:fix

# Type checking
pnpm typecheck

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

Contribution Process

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Make your changes
  4. Run tests: pnpm test
  5. Run linter: pnpm lint
  6. Run typecheck: pnpm typecheck
  7. Commit using conventional commits: git commit -m 'feat: add my feature'
  8. Push: git push origin feature/my-feature
  9. Open a Pull Request

Conventional Commits

Use conventional commit messages:

  • feat: - New features
  • fix: - Bug fixes
  • docs: - Documentation changes
  • refactor: - Code refactoring
  • test: - Test additions/changes
  • chore: - Maintenance tasks

Adding New Modules

  1. Create the module file in the appropriate templates/ directory
  2. Add entry to _registry.json with full metadata
  3. Update tests if needed
  4. Update documentation

License

MIT License - see LICENSE for details.

Author

Leandro Asrilevich

Acknowledgments

About

CLI tool to install and manage Claude Code configurations with interactive wizards, bundles, agents, skills, commands, MCP servers and standards. Supports customizable project setup with smart defaults and modular configuration.

Topics

typescript skills commands developer-tools bundles ai-agents cli-tool code-standards agentic interactive-configuration prompt-templates mcp-servers claude-code-config

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 6

v0.6.0 Latest
Dec 22, 2025
+ 5 releases

Packages

 
 
 

Contributors

Languages