for Claude Code command line
A lightweight + modular documentation framework designed for AI-assisted development with Claude Code.
Important
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!
Create a comprehensive, interconnected scaffolded documentation system that helps Claude Code understand and navigate your codebase more effectively, and retain better context.
- Quick Start
- What It Does
- Documentation Templates
- Installation Options
- Features
- CLI Commands
- Example Output
- Best Practices
- Next Steps After Installation
- Framework Philosophy
- Contributing
- Privacy & Security
- License
# 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 /Users/thomas/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 directoryClaude 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)
- 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)
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
npx claude-conductorInstall 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-conductorOnce 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 foldernpm install --save-dev claude-conductorAdd to package.json:
{
"scripts": {
"docs:init": "claude-conductor"
}
}- Detects your tech stack automatically
- Identifies main files and entry points
- Counts lines of code
- Maps directory structure
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
- Each aspect gets its own focused file
- Cross-linked for easy navigation
- Optimized for AI comprehension
- Keyword sections for searchability
- Continuous changelog in JOURNAL.md
- Auto-archives when exceeding 500 lines
- Tracks major changes, bug fixes, and decisions
- Links to error tracking system
- P0/P1 critical error ledger
- Systematic error ID format
- Links between errors and fixes
- Resolution tracking
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 helpclaude-conductor checkup [options]
claude-conduct checkup [options]
Options:
-p, --path <path> Path to check (defaults to current directory)
-h, --help Display helpThe 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.
Warning
The backup/restore upgrade system is NEW and EXPERIMENTAL. While extensively tested, it has not been used by many users in production yet.
BEFORE USING THE UPGRADE SYSTEM:
- ✅ ALWAYS create a full backup of your entire project
- ✅ Commit all changes to Git first
- ✅ Test on a copy of your project first
- ✅ Have a rollback plan ready
This feature will be marked stable after more real-world usage. You have been warned!
Claude Conductor features a bulletproof 3-step upgrade process that guarantees zero data loss:
claude-conductor backup- Safely backs up your
JOURNAL.mdandCLAUDE.mdto./conductor-backup/ - Idempotent - safe to run multiple times
- Gracefully handles missing files
claude-conductor upgrade --clean- Requires
--cleanflag for safety (prevents accidental runs) - Requires backup first (refuses to run without backup unless
--force) - Deletes ALL conductor files and reinstalls fresh templates
- Add
--fullto install all 12 templates
claude-conductor restore- Restores your backed up files exactly as they were
- Adds upgrade journal entry to document the upgrade
- Cleans up backup folder after successful restore
# Safe upgrade process for any version
npx claude-conductor backup
npx claude-conductor upgrade --clean
npx claude-conductor restore
# Upgrade to full template set
npx claude-conductor backup
npx claude-conductor upgrade --clean --full
npx claude-conductor restore- Zero Risk: Your data is physically moved out of harm's way
- Clear Process: "Save work → Get fresh templates → Put work back"
- Works for Any Upgrade: Same process for minor or major versions
- User Confidence: You can see your backup folder and know data is safe
- No Complex Merging: Avoids bugs that could corrupt your files
- Backup validation before each step
- Clear error messages for every failure scenario
- Step-by-step guidance with visual progress indicators
- Edge case handling for permissions, disk space, corrupted files
- Comprehensive test coverage ensuring reliability
After running npx claude-conductor, you'll have:
your-project/
├── CONDUCTOR.md # Master template reference
├── CLAUDE.md # AI guidance (customized)
├── ARCHITECTURE.md # Tech stack documentation
├── BUILD.md # Build instructions
└── JOURNAL.md # Dev changelog (first entry)
With --full flag:
your-project/
├── CONDUCTOR.md
├── CLAUDE.md
├── ARCHITECTURE.md
├── BUILD.md
├── API.md
├── CONFIG.md
├── DATA_MODEL.md
├── DESIGN.md
├── UIUX.md
├── TEST.md
├── CONTRIBUTING.md
├── ERRORS.md
├── JOURNAL.md
└── PLAYBOOKS/
└── DEPLOY.md
These are EXAMPLES showing how Claude Conductor populates ARCHITECTURE.md for a hypothetical React/Express project (not Claude Conductor's own dependencies):
## Tech Stack
- **Language**: Node.js/npm
- **Main File**: src/index.js (234 lines)
- **Line Count**: 5,432 total lines## Tech Stack
- **React 18.2.0**
- **TypeScript 5.1.6**
- **Tailwind CSS 3.3.3**
- **Express 4.18.2**
### Key Dependencies
- axios: ^1.4.0
- react-router-dom: ^6.14.2
- @reduxjs/toolkit: ^1.9.5
## API Endpoints
- POST /api/auth/login (src/routes/auth.js)
- GET /api/users/:id (src/routes/users.js)
- GET /api/posts (src/routes/posts.js)Note: Claude Conductor itself only uses Commander, fs-extra, glob, and chalk. The above shows what YOUR project's ARCHITECTURE.md might contain.
Begin with core templates and let your documentation grow organically:
npx claude-conductorFor mature codebases, use deep scan to capture comprehensive details:
npx claude-conductor --deepscanAfter initialization:
- Review CLAUDE.md and update the Critical Context section
- Customize templates to match your project's needs
- Remove sections that don't apply
The JOURNAL.md file is your development history:
- Add entries for significant changes
- Document debugging sessions
- Track architectural decisions
- Link to error resolutions
When working with Claude Code:
- Claude will reference your documentation automatically
- Updates happen organically during development
- Cross-links help Claude navigate efficiently
After running npx claude-conductor, your documentation templates contain placeholders. To populate them with your project details:
Simply ask Claude:
"Please review this codebase and update the CLAUDE.md and CONDUCTOR.md files with the actual project details. Also perform a security health check and list any potential vulnerabilities or concerns (like exposed .env files, API keys in code, missing .gitignore entries, outdated dependencies with known vulnerabilities, or insecure configurations) - just list them as warnings, don't fix anything."
For a more thorough initialization, ask Claude:
"Please thoroughly review this codebase, update CLAUDE.md with project context, and use CONDUCTOR.md as a guide to fill out all the documentation files. Also check for any syntax errors, bugs, or suggestions for improvement. Additionally, perform a comprehensive security health check and list any potential vulnerabilities or concerns (like exposed .env files, API keys in code, missing .gitignore entries, outdated dependencies with known vulnerabilities, insecure configurations, or other security best practice violations) - just list them as warnings, don't fix anything."
- ✅ Analyze your codebase structure and dependencies
- ✅ Fill in the Critical Context section with actual project details
- ✅ Update file references with real line numbers
- ✅ Populate architecture, build, and API documentation
- ✅ Create meaningful task templates based on your workflow
- ✅ Set up proper cross-linking between documents
- Security Health Check (New): Scan for common vulnerabilities and security concerns
⚠️ Warning List: Flag any security issues found (without making changes)
Note: Claude sees the CLAUDE.md file automatically when it's in your codebase, but won't populate the templates unless asked. This one-time setup ensures your documentation is tailored to your specific project.
If Claude Conductor detects an existing CLAUDE.md file, it will preserve it and skip creating a new one. To ensure optimal integration with the Conductor framework, please manually add this section to your existing CLAUDE.md:
## Journal Update Requirements
**IMPORTANT**: Update JOURNAL.md regularly throughout our work sessions:
- After completing any significant feature or fix
- When encountering and resolving errors
- At the end of each work session
- When making architectural decisions
- Format: What/Why/How/Issues/Result structureThis ensures Claude maintains a detailed development history in JOURNAL.md, which is a core feature of the Conductor framework.
For Security Checkups: Use the npx claude-conduct checkup command whenever you want to check for vulnerabilities.
- Modular > Monolithic - Separate concerns into focused files
- Practical > Theoretical - Include real examples and patterns
- Maintained > Stale - Regular updates through development
- Navigable > Comprehensive - Easy to find what you need
We welcome contributions! See our Contributing Guide for guidelines.
Claude Conductor is a completely offline tool that:
- ✅ Never collects or transmits any data
- ✅ Makes zero network requests
- ✅ Has no analytics or telemetry
- ✅ Works entirely on your local machine
- ✅ Only reads/writes files you explicitly specify
- Creates markdown documentation templates in your project
- Analyzes your local codebase structure (file names and patterns only)
- Updates documentation based on what it finds locally
- ❌ Send any data to external servers
- ❌ Collect personal information
- ❌ Track usage or metrics
- ❌ Make network requests (except for package installation from npmjs)
- ❌ Access environment variables or credentials
- ❌ Execute arbitrary commands
Our documentation website (not the CLI tool) uses browser local storage solely to:
- Remember your light/dark theme preference
- This data never leaves your browser
- 🚫 No cookies or tracking of any kind
This entire codebase is open source. You can verify our privacy commitment by reviewing the source code at github.com/superbasicstudio/claude-conductor.
Super Basic Studio, LLC is committed to developer privacy. This tool is simply a collection of markdown templates designed to help Claude Code AI assistant better understand and navigate your codebase.
For more details:
BSD 2-Clause © Super Basic Studio
Made with love by Super Basic Studio
claude, claude code, documentation, ai development, conductor, framework, claude conductor, vibe coding, super basic studio
