[!IMPORTANT]
⚠️ Open Source Project Notice
This is open source software currently maintained by ONE individual in their free time (which isn't much at the moment!)
While the code is tested thoroughly before releases to npm, you should ALWAYS have:
- ✅ A proper GitHub/Git strategy in place
- ✅ Regular backups of your work
- ✅ Version control before running ANY script from the internet
Especially from someone you don't know!
DISCLAIMER: This software is provided "as is" without warranty of any kind. Super Basic Studio and the maintainers of Claude Conductor are not responsible for any issues, data loss, or damages that may occur from using this tool. By using Claude Conductor, you acknowledge that you run it at your own risk and take full responsibility for backing up your code and using proper version control.
Note for Vibe Coders & Open Source Newcomers: This isn't meant to scare you away! These warnings are standard practice in open source. We're just being transparent about responsibilities - like how every tool comes with safety instructions. Follow the backup advice above and you'll be fine!
Star History
Create a comprehensive, interconnected scaffolded documentation system that helps Claude Code understand and navigate your codebase more effectively, and retain better context.
Table of Contents
- Requirements
- Quick Start
- What It Does
- Documentation Templates
- Installation Options
- Features
- CLI Commands
- Example Output
- Best Practices
- Next Steps After Installation
- Framework Philosophy
- Companion Project: Claude Anchor
- Contributing
- Privacy & Security
- License
External Resources
- Claude Anchor — Companion behavioral framework
- Changelog
- Security Policy
- Privacy Policy
- Terms of Service
- Acknowledgments
Requirements
- Node.js >= 20.0.0
Upgrading from 1.x? Version 2.0.0+ requires Node.js 20 or higher. Node 18 reached end-of-life in April 2025. If you need to stay on Node 18, pin to
claude-conductor@2.1.x.
Quick Start
# Initialize with core templates (recommended)
npx claude-conductor
# Or use the shorthand
npx claude-conduct
# Initialize in a specific directory
npx claude-conductor ./my-project
npx claude-conduct ~/projects/myapp
# Initialize with all 13 documentation templates
npx claude-conductor --full
# Force overwrite existing files
npx claude-conductor --force
# Perform deep codebase analysis (slower but more detailed)
npx claude-conductor --deepscan
# Combine path and options
npx claude-conduct ./docs --full --deepscan
# Run security checkup
npx claude-conductor checkup
npx claude-conduct checkup
npx claude-conduct checkup -p ./src # Check specific directory
What It Does
Claude Conductor creates a structured documentation framework that:
- Organizes your project documentation into focused, interconnected modules
- Optimizes for AI navigation with line numbers, anchors, and keywords
- Tracks development history with an auto-archiving journal system
- Monitors critical errors with a dedicated error ledger
- Analyzes your codebase to pre-populate documentation
- Manages active tasks with phase tracking and context preservation (NEW: TASKS.md)
Documentation Templates
Core Templates (Default)
- CONDUCTOR.md - Master navigation hub and framework reference
- CLAUDE.md - AI assistant guidance tailored to your project
- ARCHITECTURE.md - System design and tech stack
- BUILD.md - Build, test, and deployment commands
- JOURNAL.md - Development changelog (auto-created)
Full Template Set (--full flag)
All core templates plus:
- API.md - API endpoints and contracts
- CONFIG.md - Configuration and environment variables
- DATA_MODEL.md - Database schema and models
- DESIGN.md - Visual design system
- UIUX.md - User interface patterns
- TEST.md - Testing strategies and examples
- CONTRIBUTING.md - Contribution guidelines
- ERRORS.md - Critical error tracking
- PLAYBOOKS/DEPLOY.md - Deployment procedures
- TASKS.md - Active task management and phase tracking
Installation Options
Option 1: npx (Recommended)
npx claude-conductor
Option 2: Global Install
Install globally with your preferred package manager:
# npm
npm install -g claude-conductor
# pnpm
pnpm add -g claude-conductor
# yarn
yarn global add claude-conductor
# bun
bun add -g claude-conductor
Once installed globally, you can run claude-conductor or claude-conduct from anywhere on your computer:
# Run from anywhere - no need to cd into the project first!
claude-conduct /path/to/your/project
claude-conduct ./my-project --full
claude-conduct ~/Documents/myapp --deepscan
# Or navigate to a project and run it there
cd /path/to/your/project
claude-conduct
# Use with optional flags and paths:
claude-conduct ./docs --full # Create all templates in ./docs
claude-conduct ./frontend --deepscan # Deep scan the frontend directory
claude-conduct ../backend --force # Force overwrite in parent's backend folder
Option 3: Add to Project
npm install --save-dev claude-conductor
Add to package.json:
{
"scripts": {
"docs:init": "claude-conductor"
}
}
Features
Intelligent Codebase Analysis
Default Analysis (Fast - 2-3 seconds)
- Detects your tech stack automatically
- Identifies main files and entry points
- Counts lines of code
- Maps directory structure
Deep Scan Analysis (--deepscan, 30-60 seconds)
All default features plus:
- Framework Detection: React, Vue, Angular, Express, Next.js versions
- Dependency Analysis: Lists all dependencies with versions
- API Mapping: Finds and documents API endpoints
- Component Discovery: Maps React/Vue components
- Build Scripts: Extracts all npm scripts
- Database Schema: Detects Prisma schemas, SQL files, models
- Updates Multiple Files: ARCHITECTURE.md and BUILD.md get detailed updates
📋 Modular Documentation
- Each aspect gets its own focused file
- Cross-linked for easy navigation
- Optimized for AI comprehension
- Keyword sections for searchability
📖 Development Journal
- Continuous changelog in JOURNAL.md
- Auto-archives when exceeding 500 lines
- Tracks major changes, bug fixes, and decisions
- Links to error tracking system
Error Tracking
- P0/P1 critical error ledger
- Systematic error ID format
- Links between errors and fixes
- Resolution tracking
CLI Commands
Initialize Documentation (Default)
claude-conductor [options] [target-dir]
Options:
-V, --version Output version number
-f, --force Overwrite existing files
--full Create all 13 documentation templates
--deepscan Perform comprehensive codebase analysis
--no-analyze Skip codebase analysis
-h, --help Display help
Security & Health Checkup
claude-conductor checkup [options]
claude-conduct checkup [options]
Options:
-p, --path <path> Path to check (defaults to current directory)
-h, --help Display help
The checkup command generates a prompt for Claude Code to perform a security and health checkup of your codebase. It checks for:
- Exposed .env files or API keys in code
- Unsafe innerHTML usage that could lead to XSS
- Missing .gitignore entries for sensitive files
- Hardcoded credentials or secrets
- Common security anti-patterns
Note: This checkup is informational only and will never modify your code.
Ultra-Safe Upgrade System
[!WARNING] ⚠️ EARLY ALPHA FEATURE - USE WITH EXTREME CAUTION
The backup/restore upgrade system is NEW and EXPERIMENTAL. While extensively tested, it has not b