🎼 Claux

Token-efficient AI automation with TOON protocol

Professional toolkit with 36+ AI agents, quality gates, health monitoring, and workflow automation powered by TOON format messaging for building robust, production-ready projects with Claude Code.

---

📋 Table of Contents

• Overview
• Features
• Key Innovations
• Quick Start
• Installation
• Documentation
• Multilingual Support
• MCP Server Configurations
• Project Structure
• Slash Commands
• Agents Ecosystem
• Skills Library
• Usage Examples
• Configuration
• Best Practices
• Troubleshooting
• Contributing
• License

---

🎯 Overview

Claux is a comprehensive automation framework designed to supercharge your development workflow with Claude Code using the TOON (Token-Optimized Object Notation) protocol. It provides:

• 🤖 36+ Specialized AI Agents — Orchestrators and workers for bugs, security, dependencies, dead code, reuse, and more
• ⚡ MCP Server Management — 7 pre-configured MCP setups for different use cases (600-5000 tokens)
• 🔧 20+ Slash Commands — Health checks, SpecKit, worktree management, releases
• 📊 Quality Gates — Automated type-checking, builds, tests, coverage, security audits
• 🎯 Skills Library — 15+ reusable utilities for validation, reporting, and automation
• 📈 Health Monitoring — Track agent performance, success rates, and ecosystem health

---

✨ Features

🎯 TOON Protocol Integration (NEW in v0.2.0)

• Token-Efficient Communication — ~40% token savings in agent-to-agent messages
• Automatic Metrics Tracking — Real-time monitoring of token usage and savings
• Stats Dashboard — claux stats command with Rich UI visualization
• Backward Compatible — Seamless fallback to JSON when needed
• Production Ready — All 5 orchestrators + 10 health workers use TOON format

🤖 AI Agents Ecosystem

• Health Orchestrators — Complete workflows for bugs, security, dependencies, dead code (TOON-enabled)
• Development Workers — LLM services, TypeScript types, cost calculation specialists
• Testing Workers — Integration tests, performance optimization, mobile responsiveness
• Database Workers — Supabase audits, API builders, database architecture
• Infrastructure Workers — Qdrant, quality validators, orchestration logic
• Meta Workers — Agent creators, skill builders

⚙️ MCP Server Configurations

Switch between 7 optimized MCP configurations based on your needs:

Configuration	Servers	Token Usage	Use Case
BASE	Context7 + Sequential Thinking	~600	Minimal, everyday use
SUPABASE	Base + Supabase (single)	~2500	Database work
SUPABASE-FULL	Base + Supabase (dual)	~3000	Multi-project database
N8N	Base + n8n automation	~2500	Workflow automation
FRONTEND	Base + Playwright + ShadCN	~2000	UI/UX development
SERENA	Base + Serena LSP	~2500	Semantic code search
FULL	All servers + Serena	~6500	Maximum capabilities

🔌 Agent Profiles (NEW!)

Selective agent loading based on project type - only load what you need:

Profile	Agents	Token Usage	Savings	Use Case
base	8	~800	82%	Minimal universal set
nextjs-full	28	~3500	22%	Complete Next.js + Supabase
health-all	15	~2000	56%	Quality checks (any language)
development	12	~1500	67%	Code review & types

Quick Start:

# List profiles
claux agents list

# Auto-detect your project
claux agents detect

# Activate a profile
claux agents activate nextjs-full

# Check status
claux agents status

See Agent Profiles Guide for custom profiles and advanced usage.

🌍 Multilingual Support (NEW!)

Built-in internationalization with automatic language detection:

Language	Code	Status
English	en	✅ Complete
Russian	ru	✅ Complete

Quick Start:

# Check current language
claux lang current

# List available languages
claux lang list

# Switch language
export CLAUX_LANG=ru
claux version

Automatic detection from system locale. See I18N Guide for details.

🚀 Slash Commands

• Health Checks — /health-bugs, /health-security, /health-deps, /health-cleanup, /health-metrics
• SpecKit — /speckit.analyze, /speckit.specify, /speckit.implement, /speckit.checklist
• Worktree Management — /worktree-create, /worktree-list, /worktree-cleanup, /worktree-remove
• Release Management — /push (automated version bumping and changelog)
• Translation — /translate-doc (English ↔ Russian)

📊 Quality Gates

Automated validation scripts:

• Bundle Size Check — Ensure production bundles stay within limits
• Security Audit — Scan for high/critical npm vulnerabilities
• Code Coverage — Validate test coverage meets thresholds

🎯 Skills Library

Reusable utilities for:

• Plan validation, report generation, changelog creation
• Git operations, error parsing, template rendering
• Quality gates execution, rollback management
• Priority scoring, version extraction

---

🔑 Key Innovations

🎯 Orchestrator Pattern

The Paradigm Shift: Transform Claude Code from doing everything directly to acting as an orchestrator that delegates complex tasks to specialized sub-agents.

Why It Matters:

• Context Preservation: Main Claude Code stays lean (~10-15K tokens vs 50K+ in standard usage)
• Specialization: Each sub-agent is expert in its domain (bug fixing, security scanning, database architecture)
• Quality Assurance: Mandatory verification after every delegation (read files + run type-check)
• Indefinite Work: Can work on project indefinitely without context exhaustion

Core Rules (from CLAUDE.md):

1. GATHER FULL CONTEXT FIRST - Read code, search patterns, check commits before delegation
2. DELEGATE TO SUBAGENTS - Provide complete context + validation criteria
3. VERIFY RESULTS - Never skip verification (read modified files, run type-check)
4. ACCEPT/REJECT LOOP - Re-delegate with corrections if verification fails
5. PER-TASK COMMITS - Run /push patch after each completed task

📋 SpecKit Enhancement: Phase 0 Planning

SpecKit (by GitHub) provides structured development workflow. We enhanced it with Phase 0: Planning.

Phase 0 Responsibilities:

1. Executor Assignment:

   • [EXECUTOR: MAIN] - Only trivial tasks (1-2 line fixes, simple imports)
   • [EXECUTOR: existing-agent] - If 100% match with existing sub-agent
   • [EXECUTOR: FUTURE-agent-name] - If no match (agent needs creation)

2. Meta-Agent Creation:

   • Launch N meta-agent-v3 calls in single message for parallel agent creation
   • Atomicity Rule: 1 Task = 1 Agent Invocation
   • After creation: Ask user to restart Claude Code

3. Research Resolution:

   • Simple research: Agent solves with available tools
   • Complex research: Create prompt in research/ directory

Why It Matters: Ensures all necessary agents exist before implementation starts, enables parallel task execution, prevents context overflow.

🤖 Meta-Agent: The Agent Factory

meta-agent-v3 creates new specialized agents in 2-3 minutes following project patterns:

• Workers - Execute tasks from plan files (5-phase structure)
• Orchestrators - Coordinate multi-phase workflows (return control pattern)
• Simple Agents - Standalone tools

How It Works:

1. Loads architecture docs (ARCHITECTURE.md + CLAUDE.md)
2. Determines agent type and requirements
3. Generates YAML frontmatter + structure + validation + error handling
4. Writes to appropriate location
5. Validates against project patterns

🔄 Return Control Pattern

Orchestrators coordinate workflows without invoking workers directly:

Orchestrator → Create plan file → Signal readiness → EXIT
↓
Main Session → Invoke worker via Task tool
↓
Worker → Execute → Validate → Report → EXIT
↓
Orchestrator → Resume → Verify → Next phase

Why Not Task Tool?: Using Task tool would create nested contexts, defeating isolation purpose.

⚙️ MCP Dynamic Switching

Problem: Each MCP server consumes 500-1500 tokens from context budget.

Solution: Python CLI dynamically switches between 6 configurations:

• BASE (~600 tokens): Context7 + Sequential Thinking (daily use)
• SUPABASE (~2500): + Supabase (database work)
• FRONTEND (~2000): + Playwright + ShadCN (UI work)
• FULL (~5000): All servers (when needed)

Benefit: Save 500-4500 context tokens by loading only what you need.

Usage:

# Interactive menu
claux mcp interactive

# Direct switch
claux mcp switch base
claux mcp switch frontend

🌳 Worktree + VS Code Integration

Parallel Feature Development:

1. Create worktrees for different features: /worktree-create feature/new-auth
2. Add .worktrees/* to VS Code workspace folders (see .claude/settings.local.json.example)
3. Switch between features via folder selector
4. Run multiple Claude Code sessions in parallel

Benefit: 3-5 features in parallel, no context pollution, isolated testing.

🔔 Webhook Integration

Task Completion Notifications (.claude/settings.local.json.example):

{
  "hooks": {
    "Stop": [
      {
        "type": "command",
        "command": "notify-send 'Claude Code' 'Task completed!'"
      }
    ]
  }
}

Use Cases: Slack notifications, system alerts, Telegram bots, log files.

Benefit: Start task, switch to other project, get notified when done.

🎯 Skills vs Agents

Skills (15+): Reusable utilities (<100 lines), stateless, invoked via Skill tool

• Examples: run-quality-gate, validate-plan-file, generate-report-header
• No context isolation, runs in caller's context

Agents (33+): Stateful workflows, context-isolated, invoked via Task tool

• Examples: bug-hunter, security-scanner, database-architect
• Full context isolation, multi-step processes

📐 Non-Traditional CLAUDE.md

Standard Practice: Store entire project history in CLAUDE.md

• Problem: Wastes context tokens on historical data

Our Innovation: CLAUDE.md as Behavioral Operating System

• Contains ONLY orchestration rules (no project history)
• Defines how to gather context BEFORE delegation
• Specifies verification rules AFTER delegation
• Forces context preservation

Result: Main Claude Code stays lean, all context gathered on-demand.

🧠 DeksdenFlow Integration (Lazy Knowledge Loading)

Inspired by deksden-flow, we implement zero-overhead context management:

Project Index (.claude/project-index.md):

• Compact project map with annotated links
• Loaded on-demand via load-project-context skill
• ~100-200 tokens when used, 0 at baseline

Session Context (.tmp/current/session/):

• context.md: Current workflow state for resumption
• log.md: Decisions, issues, learnings (write-only)
• Enables seamless session continuation

Why It Matters:

• Resume health workflows after session restart
• Track decisions for debugging
• Navigate codebase without full exploration

Token Impact: Zero baseline overhead. Skills load context only when needed.

🔬 Serena LSP Integration

Serena MCP provides semantic code understanding via Language Server Protocol:

• Symbol Search: Find functions, classes, types by name
• Reference Lookup: "Find all usages of X"
• Intelligent Refactoring: Rename with full reference awareness
• Context: ide-assistant mode avoids tool duplication

When to Use: Large codebases where Grep produces too many false positives.

---

🚀 Quick Start

⚡ NEW: Python Package (Easiest & Cross-Platform)

Install via pip - works on Windows, macOS, and Linux without Git Bash:

# Install globally
pip install claux

# Auto-discover and setup all your projects
claux wizard setup

# Or install to specific project
claux init /path/to/project

Why Python package?

• ✅ One command installation via pip
• ✅ Works natively on Windows (no Git Bash needed)
• ✅ Auto-discovers all git projects
• ✅ Detects project types (Next.js, Django, FastAPI, etc.)
• ✅ Recommends optimal MCP configuration
• ✅ Interactive project selection
• ✅ Available globally from any directory

Setup wizard features:

# Search in default locations (~/PycharmProjects, ~/projects, ~/Documents)
claux wizard setup

# Search in custom directory
claux wizard setup -s ~/my-projects

# Auto-accept all (useful for CI)
claux wizard setup -y

Quick start guide: QUICK-START.md

---

📝 Development Installation

For contributors or local development:

# 1. Clone repository
git clone https://github.com/Gerrux/claux.git
cd claux-kit

# 2. Install in editable mode
pip install -e .

# 3. Test commands
claux version
claux wizard setup

# Your development environment is ready!

---

📦 Installation

Prerequisites

• Claude Code installed
• Python 3.8+ (for pip installation)
• Node.js 18+ (for MCP servers)
• Docker (optional, for n8n MCP server)
• Git (for version control features)

Python Package Installation (Recommended)

Easiest method - works on all platforms:

# Install via pip
pip install claux

# Verify installation
claux version

# Setup wizard (auto-discovers projects)
claux wizard setup

Auto-Update (Built-in):

Claux automatically checks for updates once per day and notifies you when a new version is available:

# Check for updates manually
claux upgrade check

# Install latest version
claux upgrade install

# Or auto-confirm
claux upgrade install -y

💡 Update notifications appear automatically when you run any command. Cache refreshes every 24 hours.

Or install to specific project:

claux init /path/to/project

Advanced usage:

# Install to specific project
claux init /path/to/project

# Search custom directory
claux wizard setup -s /path/to/projects

# Auto-detect best profile
claux agents detect

# Switch MCP interactively
claux mcp interactive

# From project directory
cd /path/to/project
claux init .

Common workflows:

# Check installation status
claux status

# Switch MCP configuration
claux mcp switch frontend    # For UI work
claux mcp interactive         # Interactive menu

# Manage agent profiles
claux agents detect           # Auto-detect best profile
claux agents activate base    # Activate profile

# Backup & restore
claux backup                  # Create backup
claux backup restore          # Restore from backup

Quick start guide: QUICK-START.md

---

🎯 Quick Configuration Modes

Minimal Mode (None)

For maximum token efficiency, disable MCP servers and custom agents:

# Disable MCP servers (saves ~600 tokens vs BASE)
bash legacy/switch-mcp.sh
# Select option 8 - NONE

# Disable custom agents (saves ~800 tokens vs BASE profile)
bash legacy/switch-agents.sh activate none

# Restart Claude Code
# Total savings: ~1400 tokens

Use Cases:

• Quick tasks without external MCP dependencies
• Testing without project customizations
• Working within tight token budgets
• CI/CD minimal configuration

See docs/NONE-MODE.md for detailed guide.

---

📚 Documentation

Comprehensive Guides

Document	Description
I18N Guide	Multilingual support - adding languages, switching, and configuration
FAQ	Frequently asked questions about agents, MCP configs, and workflows
Architecture	System design with Mermaid diagrams and workflow patterns
Tutorial: Custom Agents	Step-by-step guide to creating workers, orchestrators, and skills
Use Cases	Real-world case studies with metrics and lessons learned
Performance Optimization	Token usage optimization and cost reduction strategies
Migration Guide	Add Orchestrator Kit to existing projects
Roadmap	Future plans and community-driven feature requests

Deep Dive Documentation

Located in docs/Agents Ecosystem/:

• AGENT-ORCHESTRATION.md — Working with orchestrators
• QUALITY-GATES-SPECIFICATION.md — Quality gates specification
• REPORT-TEMPLATE-STANDARD.md — Standard report format for workers
• spec-kit-comprehensive-updates.md — SpecKit customization guide

Quick Links

• New to the kit? Start with Quick Start → Tutorial
• Want examples? See Use Cases and Usage Examples
• Need help? Check FAQ → Troubleshooting
• Optimizing costs? Read Performance Optimization
• Migrating? Follow Migration Guide

---

🔌 MCP Server Configurations

All MCP configurations are stored in ./mcp/ directory.

Available Configurations

BASE (mcp/.mcp.base.json)

{
  "mcpServers": {
    "context7": { ... },              // Library documentation
    "server-sequential-thinking": { ... }  // Enhanced reasoning
  }
}

Use for: Daily development, minimal token usage

---

SUPABASE (mcp/.mcp.supabase-only.json)

{
  "mcpServers": {
    "context7": { ... },
    "server-sequential-thinking": { ... },
    "supabase": { ... }               // Main Supabase project
  }
}

Use for: Database design, RLS policies, SQL queries

---

FULL (mcp/.mcp.full.json)

{
  "mcpServers": {
    "context7": { ... },
    "server-sequential-thinking": { ... },
    "supabase": { ... },
    "supabase-legacy": { ... },       // Secondary project
    "n8n-workflows": { ... },         // Workflow automation
    "n8n-mcp": { ... },               // n8n server control
    "playwright": { ... },            // Browser automation
    "shadcn": { ... }                 // UI components
  }
}

Use for: Full-featured development, maximum capabilities

---

Switching Configurations

# Interactive menu (recommended)
claux mcp interactive

# Direct switch
claux mcp switch base
claux mcp switch frontend
claux mcp switch supabase

# Check current config
claux mcp status

Remember: Restart Claude Code after switching!

---

📁 Project Structure

claux-kit/
│
├── 📂 .claude/                       # Main orchestration system
│   ├── agents/                       # 33+ AI agents
│   │   ├── health/                   # Bug, security, deps, cleanup orchestrators
│   │   │   ├── orchestrators/        # Multi-phase workflow coordinators
│   │   │   └── workers/              # Specialized execution agents
│   │   ├── development/              # LLM, TypeScript, cost specialists
│   │   ├── testing/                  # Integration, performance, mobile tests
│   │   ├── database/                 # Supabase, API builders
│   │   ├── infrastructure/           # Qdrant, quality validators
│   │   ├── frontend/                 # UI/UX specialists
│   │   ├── documentation/            # Technical writers
│   │   ├── research/                 # Deep-dive investigators
│   │   └── meta/                     # Agent and skill creators
│   │
│   ├── commands/                     # 19+ slash commands
│   │   ├── health-*.md               # Health monitoring workflows
│   │   ├── speckit.*.md              # Specification toolkit
│   │   ├── worktree-*.md             # Git worktree management
│   │   ├── push.md                   # Release automation
│   │   └── translate-doc.md          # Documentation translation
│   │
│   ├── skills/                       # 15+ reusable utilities
│   │   ├── validate-plan-file/       # Schema validation
│   │   ├── run-quality-gate/         # Automated checks
│   │   ├── rollback-changes/         # Restore files
│   │   ├── generate-report-header/   # Standardized reports
│   │   └── ...
│   │
│   ├── schemas/                      # JSON schemas for validation
│   │   ├── base-plan.schema.json
│   │   ├── bug-plan.schema.json
│   │   ├── security-plan.schema.json
│   │   └── ...
│   │
│   └── scripts/                      # Automation scripts
│       ├── release.sh                # Version bumping
│       └── gates/                    # Quality gate checks
│           ├── check-bundle-size.sh
│           ├── check-security.sh
│           └── check-coverage.sh
│
├── 📂 mcp/                           # MCP server configurations
│   ├── .mcp.base.json                # Minimal (~600 tokens)
│   ├── .mcp.supabase-only.json       # Database work (~2500)
│   ├── .mcp.supabase-full.json       # Multi-project (~3000)
│   ├── .mcp.n8n.json                 # Automation (~2500)
│   ├── .mcp.frontend.json            # UI/UX (~2000)
│   └── .mcp.full.json                # All servers (~5000)
│
├── 📂 .github/                       # GitHub Actions (optional)
│   └── workflows/
│
├── 🔧 Configuration Files
│   ├── .env.example                  # Environment template
│   ├── .env.local                    # Your credentials (git-ignored)
│   ├── .gitignore                    # Security exclusions
│   ├── .mcp.json                     # Active MCP config
│   └── CLAUDE.md                     # Behavioral Operating System
│
└── 📜 Python CLI
    ├── claux/                      # Python package
    │   ├── cli.py                    # Main CLI entry
    │   ├── commands/                 # All commands
    │   └── core/                     # Core functionality
    └── README.md                     # This file

---

🎯 Slash Commands

Health Monitoring

/health-bugs

Complete bug detection and fixing workflow.

What it does:

• Scans entire codebase for bugs
• Categorizes by priority (critical → high → medium → low)
• Fixes bugs stage by stage
• Runs quality gates after each stage
• Verification scan and iterative refinement

Usage:

/health-bugs

Output: bug-hunting-report.md, bug-fixes-implemented.md

---

/health-security

Security vulnerability detection and remediation.

Checks for:

• SQL injection vulnerabilities
• XSS attack vectors
• Authentication/authorization issues
• RLS policy gaps
• Hardcoded secrets

Usage:

/health-security

---

/health-deps

Dependency audit and safe updates.

Features:

• Detects outdated packages
• Finds security vulnerabilities
• Identifies unused dependencies
• One-at-a-time update strategy
• Validation and rollback support

Usage:

/health-deps

---

/health-cleanup

Dead code detection and removal.

Finds:

• Unused imports
• Commented code blocks
• Unreachable code paths
• Debug artifacts (console.log, debugger)
• Unused variables/functions

Usage:

/health-cleanup

---

/health-reuse

Code duplication detection and consolidation.

Features:

• Detects duplicated types, interfaces, and schemas
• Identifies repeated logic patterns
• Consolidates duplicates into Single Source of Truth (SSOT)
• Refactors consuming code to use shared definitions
• Prevents technical debt accumulation

Usage:

/health-reuse

---

/health-metrics

Monthly ecosystem health reports.

Analyzes:

• Agent performance and success rates
• Quality gate pass rates
• Context7 usage and effectiveness
• Complexity distribution
• Behavioral OS health

Usage:

# Current month
/health-metrics

# Specific month
/health-metrics 2025-10

# Previous month
/health-metrics last-month

Output: docs/reports/metrics/YYYY-MM-ecosystem-health.md

---

SpecKit Commands

Specification-driven development toolkit.

Command	Purpose
/speckit.analyze	Analyze requirements and extract key points
/speckit.specify	Generate detailed specifications
/speckit.clarify	Ask clarifying questions
/speckit.plan	Create implementation plan
/speckit.implement	Execute implementation
/speckit.checklist	Generate QA checklist
/speckit.tasks	Break into actionable tasks
/speckit.constitution	Define project constitution

---

Worktree Management

Git worktree automation for parallel work.

Command	Purpose
/worktree-create	Create new worktree
/worktree-list	List all worktrees
/worktree-cleanup	Clean up merged worktrees
/worktree-remove	Remove specific worktree

---

Other Commands

/push [patch|minor|major]

Automated release management.

Features:

• Analyzes commits since last release
• Auto-detects version bump type
• Updates package.json
• Generates changelog entry
• Creates git tag
• Pushes to remote

Usage:

/push patch   # 1.0.0 → 1.0.1
/push minor   # 1.0.0 → 1.1.0
/push major   # 1.0.0 → 2.0.0

---

/translate-doc

Translate documentation between English and Russian.

Usage:

/translate-doc path/to/doc.md

---

🤖 Agents Ecosystem

Architecture

Orchestrators → Plan workflows, create tasks, validate outputs, manage iterations Workers → Execute specific tasks, generate reports, return control Skills → Reusable utilities for validation, reporting, automation

Health Orchestrators

bug-orchestrator

Manages complete bug fixing workflow.

Phases:

1. Pre-flight validation
2. Bug detection (via bug-hunter)
3. Quality gate 1 (validation)
4. Staged fixing by priority
5. Quality gates per priority
6. Verification scan
7. Iterative refinement (up to 3 cycles)
8. Final summary

Key Features:

• Priority-based fixing (critical → low)
• Quality gates (type-check, build, tests)
• Rollback on failure
• Iteration tracking
• Comprehensive reporting

---

security-orchestrator

Security vulnerability workflow.

Similar to bug-orchestrator but for:

• Security vulnerabilities
• Authentication issues
• Authorization bypasses
• Data exposure risks
• Secrets management

---

dependency-orchestrator

Safe dependency update workflow.

Features:

• Audit existing dependencies
• One-at-a-time update strategy
• Validation after each update
• Rollback on failure
• Lock file management

---

dead-code-orchestrator

Dead code cleanup workflow.

Targets:

• Unused imports
• Commented code
• Unreachable paths
• Debug leftovers
• Orphaned functions

---

reuse-orchestrator

Code duplication elimination workflow.

Phases:

1. Detection: reuse-hunter scans for duplicated types/logic
2. Analysis: Group duplicates and identify best SSOT location
3. Consolidation: reuse-fixer merges duplicates into shared files
4. Refactoring: Updates all references to point to SSOT
5. Validation: Ensures no breaking changes via quality gates

---

Worker Agents

Development

• llm-service-specialist — LLM integration, prompt engineering
• typescript-types-specialist — Type definitions, generics
• cost-calculator-specialist — Token usage, API cost estimation

Testing

• integration-tester — Database, API, async job tests
• performance-optimizer — Core Web Vitals, PageSpeed
• mobile-responsiveness-tester — Viewport testing, mobile UX
• accessibility-tester — WCAG compliance, screen readers

Database

• database-architect — PostgreSQL schema design, migrations
• api-builder — tRPC routers, auth middleware
• supabase-auditor — RLS policies, security validation

Infrastructure

• infrastructure-specialist — Supabase, Qdrant, Redis, BullMQ setup
• qdrant-specialist — Vector database operations
• quality-validator-specialist — Quality gate validation

Meta

• skill-builder-v2 — Create new skills following SKILL.md format
• agent-creator — Generate new agents with proper structure

---

🎯 Skills Library

Reusable utilities accessible via Skill tool.

Validation Skills

Skill	Purpose
validate-plan-file	Verify plan JSON schema
validate-report-file	Check report completeness
validate-context7-availability	Verify Context7 MCP server status

Quality Skills

Skill	Purpose
run-quality-gate	Execute type-check/build/tests
check-infinite-loop	Detect agent invocation loops
calculate-complexity-score	Analyze task complexity (0-10)
calculate-priority-score	Score bugs/tasks by severity

Reporting Skills

Skill	Purpose
generate-report-header	Create standardized report headers
format-markdown-table	Generate well-formatted tables
format-todo-list	Create TodoWrite-compatible lists
generate-changelog	Generate changelog from commits

Utility Skills

Skill	Purpose
parse-git-status	Parse git status into structured data
parse-package-json	Extract version, dependencies
parse-error-logs	Parse build/test errors
extract-version	Parse semantic version strings
format-commit-message	Generate conventional commits
render-template	Variable substitution in templates
rollback-changes	Restore files from changes log

Context & Session Skills (DeksdenFlow)

Skill	Purpose
load-project-context	Load project index for navigation
save-session-context	Save workflow state for resumption
resume-session	Resume previously saved session

---

💡 Usage Examples

Example 1: Complete Bug Fixing Workflow

# 1. Run bug detection and fixing
/health-bugs

# Agent workflow:
# - Pre-flight validation
# - Scans codebase (bug-hunter)
# - Finds 45 bugs (12 critical, 18 high, 10 medium, 5 low)
# - Fixes critical bugs first
# - Runs type-check ✅, build ✅, tests ✅
# - Fixes high priority bugs
# - Quality gates ✅
# - Verification scan
# - Final report generated

# 2. Review results
cat bug-hunting-report.md
cat bug-fixes-implemented.md

# 3. Review monthly metrics
/health-metrics

---

Example 2: Switching MCP for Frontend Work

# Switch to frontend config (Playwright + ShadCN)
claux mcp switch frontend

# Or use interactive menu
claux mcp interactive

# Restart Claude Code

# Now you have access to:
# - Playwright for browser automation
# - ShadCN for UI component generation
# - Context7 for library docs
# - Sequential Thinking for complex reasoning

---

Example 3: Worktree Workflow

# Create worktree for feature development
/worktree-create feature/new-auth-flow

# Work in parallel worktree
cd .worktrees/feature-new-auth-flow
# ... make changes ...

# List all worktrees
/worktree-list

# Cleanup merged worktrees
/worktree-cleanup

---

Example 4: Release Automation

# Auto-detect version bump and release
/push

# Or specify version bump type
/push minor

# What happens:
# 1. Analyzes commits since last release
# 2. Detects features, fixes, breaking changes
# 3. Bumps version in package.json
# 4. Generates changelog entry
# 5. Creates git commit + tag
# 6. Pushes to remote

---

⚙️ Configuration

Environment Variables

All sensitive data is stored in .env.local (git-ignored).

Required for Supabase MCP:

SUPABASE_PROJECT_REF=abc123xyz
SUPABASE_ACCESS_TOKEN=sbp_yourtokenhere
SUPABASE_DB_PASSWORD=yourpassword

Required for Sequential Thinking:

SEQUENTIAL_THINKING_KEY=your-smithery-key
SEQUENTIAL_THINKING_PROFILE=your-profile-name

Optional for n8n:

N8N_API_URL=https://your-n8n.com
N8N_API_KEY=your-api-key

MCP Configuration Template

MCP configs use environment variable interpolation:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref=${SUPABASE_PROJECT_REF}"],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}"
      }
    }
  }
}

Variables are automatically resolved from .env.local.

---

📚 Best Practices

1. Start with BASE Configuration

Use minimal MCP config for daily work to conserve tokens:

claux mcp switch base
# Or use interactive menu
claux mcp interactive

Switch to specialized configs only when needed.

---

2. Run Health Checks Weekly

# Monday: Bug scan
/health-bugs

# Tuesday: Security audit
/health-security

# Wednesday: Dependency check
/health-deps

# Thursday: Dead code cleanup
/health-cleanup

# End of month: Metrics review
/health-metrics

---

3. Use Quality Gates

Always enable quality gates in orchestrators:

{
  "validation": {
    "required": ["type-check", "build"],
    "optional": ["tests"]
  }
}

---

4. Monitor Agent Performance

Check monthly metrics to identify issues:

/health-metrics

# Look for:
# - Success rate < 85% (needs improvement)
# - Underutilized agents (< 5 invocations/month)
# - Quality gate failures
# - Fallback strategy triggers

---

5. Keep .env.local Secure

# Never commit
echo ".env.local" >> .gitignore

# Use strong credentials
# Rotate tokens regularly
# Use environment-specific values

---

6. Adopt Library-First Approach

Before writing new custom code (>20 lines), always search for existing solutions:

1. Search: Check npm/PyPI for libraries with >1k weekly downloads
2. Evaluate: Check maintenance status, types support, and bundle size
3. Adopt: Use library if it covers >70% of functionality
4. Build: Only write custom code for unique business logic or when no good library exists

Why? Reduces maintenance burden, leverages community testing, and speeds up development.

---

🔧 Troubleshooting

MCP Server Not Working

Problem: MCP server not showing up after switch

Solution:

# 1. Verify config was copied
cat .mcp.json

# 2. Check environment variables
cat .env.local

# 3. Restart Claude Code completely
# (not just reload)

# 4. Check Claude Code logs for errors

---

Quality Gates Failing

Problem: Type-check or build keeps failing

Solution:

# 1. Run manually to see full errors
npm run type-check
npm run build

# 2. Check for TypeScript issues
npx tsc --noEmit

# 3. Review validation settings
cat .claude/scripts/gates/check-*.sh

---

Agent Workflow Stuck

Problem: Orchestrator workflow not progressing

Solution:

# 1. Check plan file
cat .tmp/current/plans/*.json

# 2. Verify reports generated
ls -la .tmp/current/reports/

# 3. Check for infinite loop
# (check-infinite-loop skill)

# 4. Review changes log
cat .tmp/current/changes/*.json

---

Environment Variables Not Loading

Problem: MCP servers show "undefined" for variables

Solution:

# 1. Verify .env.local exists
ls -la .env.local

# 2. Check format (no quotes needed)
cat .env.local
# Correct: SUPABASE_PROJECT_REF=abc123
# Wrong: SUPABASE_PROJECT_REF="abc123"

# 3. Restart Claude Code
# Variables load on startup

---

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

Adding New Agents

1. Create agent file in appropriate category:

   .claude/agents/{category}/workers/my-agent.md
   

2. Follow agent template structure

3. Include examples and test cases

4. Update this README with agent description

Adding New Skills

1. Create skill directory:

   .claude/skills/my-skill/SKILL.md
   

2. Follow SKILL.md format

3. Add to Skills Library section in README

Adding MCP Configurations

1. Create config in mcp/ directory
2. Follow naming convention: .mcp.{name}.json
3. Use environment variables for secrets
4. Update switch-mcp.sh menu
5. Document in README

---

📄 License

MIT License - See LICENSE file for details.

---

🏆 Attribution

This project includes components adapted from:

SpecKit by GitHub

The SpecKit commands (/speckit.*) are adapted from GitHub's SpecKit project.

• License: MIT License
• Copyright: GitHub, Inc.
• Components: speckit.analyze, speckit.specify, speckit.clarify, speckit.plan, speckit.implement, speckit.checklist, speckit.tasks, speckit.constitution

Special thanks to the GitHub team for creating this excellent specification-driven development toolkit.

---

🙏 Acknowledgments

Built with and powered by:

• Claude Code by Anthropic The official CLI for Claude that powers this entire orchestration system

• Context7 by Upstash Real-time library documentation and best practices through MCP

• Smithery Sequential Thinking Enhanced reasoning capabilities through structured thinking

• Supabase MCP Server Database access and management through Model Context Protocol

• n8n Workflow automation platform integration

• Playwright Browser automation for testing and validation

• shadcn/ui Beautiful UI component system

Special thanks to the open-source community and all contributors!

---

🔗 Links

• GitHub Repository: claux-kit
• Author: Ilya Kalinin
• Documentation: Full Docs
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

📊 Project Stats

• 36+ AI Agents (Orchestrators + Workers)
• 20+ Slash Commands
• 18+ Reusable Skills
• 7 MCP Configurations (including Serena LSP)
• 3 Quality Gate Scripts
• 100% Environment Variable Security

---

👤 Author

Ilya Kalinin

• GitHub: @Gerrux
• Email: kalinin.ilya29@gmail.com
• Repository: claux

---

Made with ❤️ for the Claude Code community

Star ⭐ this repo if you find it useful!

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

TL;DR: Free to use, modify, and distribute. Just keep the copyright notice.