claude-conductor

Claude Conductor Logo

Claude Conductor

for Claude Code command line

A lightweight + modular documentation framework designed for AI-assisted development with Claude Code.

npm version npm downloads license

[!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:

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.

Table of Contents

External Resources

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 /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 directory

What It Does

⬆ Back to top

Claude Conductor creates a structured documentation framework that:

Documentation Templates

⬆ Back to top

Core Templates (Default)

Full Template Set (–full flag)

All core templates plus:

Installation Options

⬆ Back to top

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

⬆ Back to top

Intelligent Codebase Analysis

Default Analysis (Fast - 2-3 seconds)

Deep Scan Analysis (–deepscan, 30-60 seconds)

All default features plus:

📋 Modular Documentation

📖 Development Journal

Error Tracking

CLI Commands

⬆ Back to top

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:

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 been used by many users in production yet.

BEFORE USING THE UPGRADE SYSTEM:

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:

Step 1: Backup Your Data

claude-conductor backup

Step 2: Clean Installation

claude-conductor upgrade --clean

Step 3: Restore Your Data

claude-conductor restore

Complete Upgrade Example

# 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

Why This Approach?

Safety Features

Example Output

⬆ Back to top

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

How Your Project’s ARCHITECTURE.md Will Look

⬆ Back to top

These are EXAMPLES showing how Claude Conductor populates ARCHITECTURE.md for a hypothetical React/Express project (not Claude Conductor’s own dependencies):

Example: ARCHITECTURE.md with Default Scan

## Tech Stack
- **Language**: Node.js/npm
- **Main File**: src/index.js (234 lines)
- **Line Count**: 5,432 total lines

Example: ARCHITECTURE.md with –deepscan

## 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.

Best Practices

⬆ Back to top

Start Lean

Begin with core templates and let your documentation grow organically:

npx claude-conductor

Use Deep Scan for Existing Projects

For mature codebases, use deep scan to capture comprehensive details:

npx claude-conductor --deepscan

Review and Customize

After initialization:

  1. Review CLAUDE.md and update the Critical Context section
  2. Customize templates to match your project’s needs
  3. Remove sections that don’t apply

Maintain Your Journal

The JOURNAL.md file is your development history:

Use with Claude Code

When working with Claude Code:

  1. Claude will reference your documentation automatically
  2. Updates happen organically during development
  3. Cross-links help Claude navigate efficiently

Next Steps After Installation

⬆ Back to top

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."

Option 2: Comprehensive Setup

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."

What Claude Will Do:

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 You Already Have a CLAUDE.md File

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 structure

This 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.

Framework Philosophy

⬆ Back to top

  1. Modular > Monolithic - Separate concerns into focused files
  2. Practical > Theoretical - Include real examples and patterns
  3. Maintained > Stale - Regular updates through development
  4. Navigable > Comprehensive - Easy to find what you need

Contributing

⬆ Back to top

We welcome contributions! See our Contributing Guide for guidelines.

Privacy & Security

⬆ Back to top

Your Data Stays Private

Claude Conductor is a completely offline tool that:

What This Tool Does:

What This Tool Does NOT Do:

Website Local Storage

Our documentation website (not the CLI tool) uses browser local storage solely to:

Open Source Transparency

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:

License

⬆ Back to top

BSD 2-Clause © Super Basic Studio

Made with love by Super Basic Studio

Keywords

claude, claude code, documentation, ai development, conductor, framework, claude conductor, vibe coding, super basic studio

This site is open source. Improve this page.