cc-devtools

A modular developer toolkit for Claude Code that provides kanban project management, persistent memory, implementation planning, source code mapping, and automated workflow orchestration capabilities.

Overview

cc-devtools is a comprehensive toolkit that extends Claude Code with powerful project management and development capabilities through MCP (Model Context Protocol) servers. Each tool operates independently and stores data in your project's cc-devtools/ directory.

MCP Tools (Claude Code Integration)

• Kanban Board - Manage stories, subtasks, and workflows with intelligent work recommendations
• Persistent Memory - Store and search project knowledge with semantic search
• Implementation Planner - Create, track, and search implementation plans with tasks
• Source Code Mapper - Index and search your codebase with semantic understanding
• Documentation Indexer - Semantic documentation search for markdown, text, and other doc formats
• Workflow Orchestration - Automated solo developer workflow with state machine and AI code reviews
• Clipboard - Copy generated content directly to system clipboard

Web Application

In addition to the MCP tools, cc-devtools includes a standalone web application that provides browser-based access to project management and development features:

• 📋 Kanban Board - Visual kanban board with drag-and-drop, customizable columns, and real-time updates
• 📝 Code Editor - Browser-based code editor with syntax highlighting and file tree navigation
• 💻 Remote Console - NEW! Web-based terminal with multiple sessions, tab management, and persistent connections
  • Full xterm.js terminal rendering with colors and formatting
  • Multiple terminal sessions in tabbed interface
  • Sessions persist across page refreshes
  • Auto-updating tab names based on current directory
  • Powered by VibeTunnel for efficient terminal streaming
  • Platform Support: macOS and Linux only (tested on macOS)

Quick Start (Web App):

# Build and start the web server
npm run build:web
npx cc-devtools web

# Or run in development mode (separate terminals)
npm run dev:web          # Frontend dev server
npx cc-devtools web      # Backend server

# Clear stored authentication tokens (if needed)
npx cc-devtools web --invalidate-tokens

Access at http://localhost:9100 (or next available port)

Web App Features:

• Token-based authentication with QR code support
• Persistent authentication tokens - tokens remain valid across server restarts
• Persistent sidebar navigation across all pages
• Responsive design for desktop browsers
• File watching for real-time kanban updates
• WebSocket connections for terminal I/O

Screenshots (click to expand):

Visual kanban board with stories, subtasks, and workflow phases

Browser-based code editor with syntax highlighting and file tree

Web-based terminal with multiple sessions and tab management

Persistent memory storage with semantic search

Implementation planning with tasks and progress tracking

📖 Web Application Documentation | 📖 Remote Console Documentation | 📖 Deployment Guide

Installation

Important: This package must be installed locally in your project (not globally) because the MCP servers need to run from your project's node_modules/ directory.

npm install @shaenchen/cc-devtools

Quick Start

1. Install the Package

npm install @shaenchen/cc-devtools

2. Run Setup

Run the interactive setup command:

npx cc-devtools setup

This will:

• Create the cc-devtools/ directory structure
• Update .gitignore to exclude cache files
• Configure .mcp.json with MCP server entries
• Optionally copy slash command templates to .claude/commands/
• Generate a recommended output-style for proactive tool usage

You can also use flags for non-interactive setup:

npx cc-devtools setup --features=kanban,memory --gitignore --mcp

3. Restart Claude Code

After setup, restart Claude Code to load the new MCP servers.

4. Start Using the Tools

The tools are now available through Claude Code's MCP tools:

• kanban_get_work_item - Get recommended work items
• kanban_update_work_item - Update story/subtask status
• memory_store - Store project memories
• memory_search - Search memories with hybrid search
• plan_store - Create implementation plans
• plan_search - Search plans and tasks
• plan_update - Update plan status and tasks
• search_code - Search code symbols semantically
• query_imports - Query import relationships
• get_file_info - Get file symbol information
• search_docs - Search documentation with semantic/exact/fuzzy modes
• clipboard_write - Copy content to system clipboard

Managing Features

Check Status

View currently enabled features and data files:

npx cc-devtools status

This displays:

• Package installation status
• Which features are enabled in .mcp.json
• Which features have data files
• Configuration status (.mcp.json, .gitignore)
• Suggested next steps

Add Features

Enable additional features after initial setup:

# Interactive mode - select features from a menu
npx cc-devtools add-feature

# With flags - specify features directly
npx cc-devtools add-feature --features=planner,memory
npx cc-devtools add-feature --features=kanban --slash-commands

This will:

• Add MCP server entries to .mcp.json for the selected features
• Optionally copy slash command templates
• Display next steps for using the new features

Note: Restart Claude Code after adding features to load the new MCP servers.

Remove Features

Disable features you no longer need:

# Interactive mode - select features and choose data handling
npx cc-devtools remove-feature

# With flags - specify features and data handling
npx cc-devtools remove-feature --features=memory --keep-data
npx cc-devtools remove-feature --features=planner --remove-data

This will:

• Remove MCP server entries from .mcp.json
• Remove slash commands (if any)
• Optionally remove data files (prompted or via flags)

⚠️ Warning: Removing features with --remove-data permanently deletes your data files. This cannot be undone.

Source Code Mapper Commands

View statistics about your indexed codebase:

# Show statistics about the indexed codebase
npx cc-devtools scm stats

This displays:

• Number of files indexed
• Total symbols found
• Breakdown by symbol type (functions, classes, etc.)
• Top files by symbol count

Note: The source code mapper works out-of-the-box using comprehensive regex parsing for all major languages. No additional installation or setup required.

Per-File Runner

Run commands on files matching glob patterns with intelligent state tracking. Perfect for batch processing files with AI tools like Claude CLI or running automated tasks on your codebase.

# View status of files (new, out-of-date, up-to-date)
npx cc-devtools per-file-runner status <config-id>

# Run command on all files that need processing
npx cc-devtools per-file-runner run <config-id>

# Run with dry-run to preview what would execute
npx cc-devtools per-file-runner run <config-id> --dry-run

# Run all configs in priority order
npx cc-devtools per-file-runner run-all

# Automatic mode: continuously run with retry logic
# Success: retry in 1 minute | Failure: retry in 1 hour
npx cc-devtools per-file-runner automatic

# Reset state to re-process all files
npx cc-devtools per-file-runner reset <config-id>

Key Features:

• MD5-based change detection (only process new or modified files)
• Prompt template with {filename} placeholder substitution
• Sequential processing with automatic state updates
• Priority-based execution for multiple configs
• Timestamped logging for all operations
• Dry-run mode for testing
• Automatic retry logic for continuous processing

Configuration: cc-devtools/per-file-runner.yaml State Tracking: cc-devtools/per-file-runner-state.yaml

📖 Full Per-File Runner Documentation

Suggest Output Style

Generate a custom Claude Code output-style tailored to your enabled cc-devtools features:

npx cc-devtools suggest-output-style

This command:

• Detects which features are currently enabled
• Generates output-style content with prescriptive guidance
• Displays the suggested content for review
• Offers to save as a new file OR append to existing output-style

Why use this?

• Workflow automation (ESSENTIAL if enabled): If you enabled the workflow feature, the output-style guidance is REQUIRED for it to function. It tells Claude when to automatically run npx cc-devtools workflow check and how to interpret and act on the results.
• Proactive tool usage (OPTIONAL): Instructs Claude to use other MCP tools autonomously without asking
• Clear behavioral directives: "Store decisions immediately", "Search before answering"
• Tool selection guidance: When to use Planner vs Memory vs TodoWrite
• Efficient context usage: Only includes guidance NOT already in MCP tool descriptions

Workflow options:

Option 1: Create new output-style

npx cc-devtools suggest-output-style
# Review generated content
# Choose "Create new"
# Enter name: "cc-devtools-enhanced"
# Restart Claude Code
# Activate: /output-style cc-devtools-enhanced

Option 2: Append to existing output-style

npx cc-devtools suggest-output-style
# Review generated content
# Choose "Append to existing"
# Select your current output-style
# Restart Claude Code (your existing style is now enhanced)

Tools Documentation

Kanban Tool

Manage project work with stories, subtasks, and customizable workflow phases.

Key Features:

• Configurable workflow phases (defaults: MVP, BETA, V1, POSTRELEASE)
• Story and subtask dependency tracking
• Intelligent work recommendations based on priorities and blockers
• Status validation and workflow enforcement
• Progress tracking and analytics
• 10 slash command templates included

Storage: cc-devtools/kanban.yaml

Customization: Phases are fully configurable via the YAML config - use the defaults or define your own phases like ALPHA, RC, PRODUCTION, etc.

MCP Tools:

• kanban_get_work_item - Get next recommended work item with reasoning
• kanban_update_work_item - Update story or subtask status with validation

Slash Commands: /kanban-next, /kanban-board, /kanban-move, /kanban-list, and more

📖 Full Kanban Documentation

Memory Tool

Store and retrieve project knowledge with semantic search capabilities.

Key Features:

• Hybrid keyword + semantic search
• Automatic embedding generation
• Cosine similarity scoring
• Persistent storage with YAML
• Category-based organization

Storage: cc-devtools/memory.yaml

MCP Tools:

• memory_store - Store memories with optional categories and metadata
• memory_search - Search with filters, limits, and similarity thresholds

📖 Full Memory Documentation

Planner Tool

Create and manage implementation plans with tasks and dependencies.

Key Features:

• Plan creation with goals and implementation notes
• Task management with status tracking
• Hybrid search across plans and tasks
• Plan status updates (planning, in_progress, completed, on_hold)
• Task completion tracking with timestamps
• Work session pause/resume with context preservation
• 2 slash command templates included

Storage: cc-devtools/planner/

MCP Tools:

• plan_store - Create new implementation plans
• plan_search - Search plans with filters and semantic search
• plan_update - Update plan status and mark tasks complete

Slash Commands: /plan-create, /plan-pause-work, /plan-resume-work

Session Management: The Planner tool includes powerful work session management via slash commands:

• /plan-create - Convert conversation into comprehensive tracked implementation plan
• /plan-pause-work - Save your current work context when stepping away
• /plan-resume-work - Resume work later with full context restoration
• Switch between multiple work streams effortlessly
• Preserve decisions and progress across sessions

See Work Session Workflow below for detailed usage guide.

📖 Full Planner Documentation

Source Code Mapper Tool

Index and search your codebase with semantic understanding.

Key Features:

• Works out-of-the-box with comprehensive regex parsing for 30+ languages
• Three search modes: exact, fuzzy, and semantic
• Import graph tracking and querying
• File symbol extraction (functions, classes, interfaces, types, variables)
• Automatic index updates via file watching
• Efficient MessagePack storage
• No external dependencies required

Storage: cc-devtools/.cache/source-code-index.msgpack

Language Support:

• JavaScript/TypeScript (full support for functions, classes, interfaces, types, enums)
• Python (functions, classes, decorators)
• Go (functions, methods, structs, interfaces)
• Java/C# (classes, interfaces, methods)
• Rust (functions, structs, traits, impls)
• Ruby, PHP, C/C++, Swift, and 20+ more languages
• View stats: npx cc-devtools scm stats

MCP Tools:

• search_code - Search code symbols with configurable modes
• query_imports - Query import relationships and dependencies
• get_file_info - Get symbols and imports for specific files

📖 Full Source Code Mapper Documentation

Documentation Indexer Tool

Index and search your documentation with semantic understanding.

Key Features:

• Works out-of-the-box with heuristic context generation (no LLM API calls)
• Multi-format support: Markdown, reStructuredText, AsciiDoc, plain text
• Three search modes: semantic, exact, and fuzzy
• Smart chunking based on document structure (headings, paragraphs)
• Automatic index updates via file watching
• Efficient MessagePack storage
• Fast context preview for quick result identification

Storage: cc-devtools/.cache/documentation-index.msgpack

Format Support:

• Markdown (.md, .markdown) - Full heading hierarchy, code blocks, lists
• reStructuredText (.rst) - Underline/overline headings, directives
• AsciiDoc (.adoc, .asciidoc) - Equal-sign headings, blocks
• Plain text (.txt) - Paragraph-based chunking

MCP Tools:

• search_docs - Search documentation with semantic/exact/fuzzy modes

📖 Full Documentation Indexer Documentation

Clipboard Tool

Copy generated content directly to your system clipboard for easy pasting.

Key Features:

• Copy any text content to system clipboard
• Cross-platform support (macOS, Windows, Linux)
• No storage or configuration needed
• Instant availability for pasting

Usage: When Claude generates content you want to use elsewhere, explicitly ask Claude to copy it to your clipboard:

You: "Can you create a summary of the API changes?"
Claude: "Here's a comprehensive summary of the API changes..."
You: "Copy that to my clipboard"
Claude: [Uses clipboard_write tool]
Claude: "✓ Summary copied to clipboard - ready to paste!"

Important: Claude will only use the clipboard tool when you explicitly request it. It won't automatically copy content.

MCP Tool:

• clipboard_write - Copy text content to system clipboard

Use Cases:

• Copy generated documentation for pasting into wikis
• Copy code snippets for use in other editors
• Copy summaries for sharing with team members
• Copy formatted content (markdown, code, etc.)

Note: The clipboard tool has no persistent storage - it simply provides a convenient way to transfer Claude's output to your clipboard.

Workflow Tool

Automated solo developer workflow orchestration with state machine and AI-powered code reviews.

Key Features:

• Decision tree-based state machine guides workflow progression
• Analyzes git branch/status and kanban state to recommend next actions
• Orchestrates multiple AI reviewers in parallel for cross-validated code reviews
• Automated workflow progression: start work → implement → commit → review → merge → done
• Fully atomic operations (one git/kanban command at a time)
• Branch-based workflow with feature branch support
• Local-first (never auto-pushes to remote)
• Configurable decision trees and reviewer configurations
• 2 slash command templates included

Storage: cc-devtools/workflow/ (config files), workflow.log (execution log)

CLI Commands:

• npx cc-devtools workflow check - Check current workflow state and get recommendations
• npx cc-devtools workflow review - Run automated code review with AI reviewers

Slash Commands: /workflow-check, /workflow-start-review

Review System: The workflow includes a sophisticated automated review system that:

• Generates comprehensive review prompts with story context
• Runs multiple AI reviewers (Claude, Codex, Qwen, Gemini) in parallel
• Collects and stores all review outputs to kanban
• Supports cross-validation to identify false positives
• Configurable reviewer timeouts and arguments
• Stores false positives to memory for learning

Workflow States: The state machine tracks git state (branch, clean status, commit messages) and kanban state (stories, subtasks, statuses) to determine current workflow state and recommend appropriate actions like:

• Starting new work on todo stories
• Creating feature branches
• Continuing implementation
• Moving to code review
• Running automated reviewers
• Merging completed work

Customization:

• Decision Tree: Fully customizable YAML decision tree (or use defaults)
• Reviewers: Configure any AI CLI tool as a reviewer
• Review Prompt: Customize the review prompt template (cc-devtools/workflow/review-prompt.md) to match your project's coding standards, security requirements, and review focus
• Logging: Configurable log levels (info, debug, error)
• Integration: Direct kanban imports or CLI mode

Requirements:

• Kanban feature - Workflow depends on kanban for state management (must be enabled together)
• Output-style guidance - ESSENTIAL for workflow to function. Setup will prompt you to generate this automatically. The workflow output-style tells Claude when to run npx cc-devtools workflow check and how to interpret the JSON results.

📖 Full Workflow Documentation

Automated Workflow Orchestration

The workflow feature is an automated solo developer workflow orchestrator that analyzes your git and kanban state, makes intelligent decisions about what to do next, and guides Claude through a complete development workflow from story creation to code review to completion.

How It Works

The workflow system is a state machine that:

1. Analyzes State: Reads git branch/status and kanban stories/subtasks via npx cc-devtools workflow check
2. Makes Decisions: Uses a YAML decision tree to determine current workflow state
3. Guides Actions: Returns actionable JSON telling Claude what to do next
4. Orchestrates Reviews: Runs multiple AI reviewers in parallel, cross-validates findings
5. Automates Flow: Automatically progresses through: start work → implement → commit → review → merge → done

Key Principles:

• One thing in progress at a time - No parallel work on multiple stories
• Branch-based workflow - Main branch only has todo and done stories
• Feature branches - Work happens on feature branches with in_progress and in_review stories
• Local-first - Git operations stay local (never auto-push)
• AI-powered reviews - Multiple AI reviewers provide cross-validated feedback

Example Decision Flow

Is git clean?
├─ No → Commit or stash changes first
└─ Yes → Are we on a feature branch?
    ├─ No → On main branch
    │   └─ Any stories in progress?
    │       ├─ Yes → Create feature branch
    │       └─ No → Start next todo story
    └─ Yes → On feature branch
        └─ Current story status?
            ├─ in_progress → Continue implementing
            ├─ in_review → Run automated review
            └─ done → Merge to main and cleanup

Setup and Usage

1. Enable Workflow Feature

# If setting up a new project
npx cc-devtools setup --features=kanban,workflow

# If adding to existing project
npx cc-devtools add-feature --features=workflow

2. Generate Output-Style (REQUIRED)

The workflow feature REQUIRES output-style guidance to function autonomously:

npx cc-devtools suggest-output-style

This creates essential workflow guidance that:

• Tells Claude when to automatically run npx cc-devtools workflow check
• Explains how to interpret and act on the JSON results
• Enables the self-perpetuating workflow loop

Without output-style guidance, Claude won't know when to run workflow checks or how to interpret results.

3. Check Workflow State

npx cc-devtools workflow check

# Output example:
{
  "state": "ready_to_start_work",
  "gitState": {
    "current_branch": "main",
    "clean": true
  },
  "kanbanState": {
    "next_item": {
      "id": "story-1",
      "title": "Implement user authentication",
      "status": "todo"
    }
  },
  "actionNecessary": "Start work on next todo story",
  "options": [
    {
      "option": "Start Story",
      "description": "Begin work on 'Implement user authentication'",
      "actionNecessary": "npx cc-devtools kanban update-work-item story-1 --status in_progress"
    }
  ]
}

4. Run Automated Code Review

When your story reaches in_review status:

# Run all enabled reviewers
npx cc-devtools workflow review

# Run specific reviewers only
npx cc-devtools workflow review claude codex

The review system:

• Generates comprehensive review prompt with story context
• Executes multiple AI CLIs in parallel (Claude, Codex, Qwen, Gemini)
• Collects all reviewer outputs
• Stores reviews to kanban story
• Supports cross-validation to identify false positives

Typical User Experience

Once workflow is set up with output-style guidance, the workflow becomes fully autonomous. Here's what a typical session looks like:

You: "What should I work on?"

Claude:

• Automatically runs npx cc-devtools workflow check
• Analyzes the JSON output
• Determines you should start story-123: "Implement user authentication"
• Updates the story to in_progress
• Creates feature branch feature/story-123
• Begins implementing the feature

Claude continues autonomously:

• Writes code, makes commits with descriptive messages
• Periodically checks workflow state
• After completing each subtask, offers options:
  • Option A: Start next subtask
  • Option B: Stop for now (you can /clear and resume again with Continue working)
• When all subtasks are complete, moves story to in_review
• Asks you to run /workflow-start-review for code review

You: /workflow-start-review

Claude:

• Runs pre-research on the story and changes
• Generates comprehensive review prompt
• Executes multiple AI reviewers in parallel (Claude, Codex, etc.)
• Cross-validates findings across reviewers
• Presents issues in interactive table
• Creates subtasks for required changes OR approves the work
• If changes needed: implements them and repeats review
• If approved: merges to main, marks story done, moves to next story

You: "Continue"

Claude:

• Checks workflow state again
• Sees next todo story
• Starts the cycle over

What happens behind the scenes:

# Claude automatically runs these commands as needed:
npx cc-devtools workflow check
npx cc-devtools kanban update-work-item <id> --status <status>
git checkout -b feature/<story-id>
git add . && git commit -m "..."
npx cc-devtools kanban create-work-item (for subtasks)
git checkout main && git merge feature/<story-id>

When Claude stops to ask you:

• After completing each subtask (offers to continue with next subtask or stop)
• When implementation is complete and ready for review (asks you to run /workflow-start-review)
• When review findings need your approval/decision
• When there are blockers that need human input
• When all work is complete

Configuration

The workflow system uses several YAML configuration files in cc-devtools/workflow/:

• config.yaml - Main workflow configuration
• decision-tree.yaml - State machine decision logic (customizable)
• reviewers.yaml - AI reviewer configuration (Claude, Codex, Qwen, Gemini)
• review-prompt.md - Review prompt template
• round-1-guidance.md / round-2-guidance.md / round-3-plus-guidance.md - Round-specific review guidance

Customizing the Decision Tree

You can customize the workflow decision logic by editing decision-tree.yaml or creating your own:

decisions:
  - name: root
    condition: "{{git_clean}} === true"
    if_true: check_branch
    if_false:
      state: uncommitted_changes
      action_type: suggest
      action: "Commit or stash your changes before proceeding"

See Decision Tree Documentation for full customization guide.

Slash Commands

• /workflow-check - Quick workflow state check and recommendations
• /workflow-start-review - Comprehensive multi-phase code review with cross-validation

For complete workflow documentation, see docs/workflow/

Technical Details

• Storage: Sessions saved in cc-devtools/plans/ as YAML files
• Identification: Plans with status="on_hold"
• Search: /plan-resume-work searches for on_hold plans only
• Automatic cleanup: Completed sessions excluded from future searches
• Persistence: Sessions survive Claude Code restarts

See Planner Slash Commands Documentation for complete technical details and examples.

Directory Structure

After setup, your project will have:

my-project/
├── package.json
├── node_modules/
│   └── @shaenchen/cc-devtools/
├── .mcp.json                  # MCP server configuration
├── .gitignore                 # Updated with cache exclusions
├── workflow.log               # Workflow execution log (gitignored)
├── .claude/
│   └── commands/              # Optional slash commands
└── cc-devtools/
    ├── kanban.yaml                  # Kanban data (created on first use)
    ├── memory.yaml                  # Memory storage (created on first use)
    ├── plans/                       # Planner storage (created on first use)
    ├── per-file-runner.yaml         # Per-file runner config
    ├── per-file-runner-state.yaml   # Per-file runner state tracking
    ├── workflow/                    # Workflow configuration (if enabled)
    │   ├── config.yaml              # Workflow settings
    │   ├── decision-tree.yaml       # Decision tree (optional custom)
    │   └── reviewers.yaml           # Reviewer configuration
    └── .cache/                      # Ephemeral cache files (gitignored)
        ├── source-code-index.msgpack     # Source code index
        ├── documentation-index.msgpack   # Documentation index
        ├── kanban-embeddings.msgpack     # Kanban search cache
        ├── memory-embeddings.msgpack     # Memory search cache
        ├── planner-embeddings.msgpack    # Planner search cache
        └── web-tokens.msgpack            # Web server auth tokens

Configuration

Setup Options

The setup command accepts these flags:

• --features=<list> - Comma-separated list of features to enable (kanban, memory, planner, source-code-mapper, documentation-indexer, workflow, clipboard)
• --gitignore - Update .gitignore with cache exclusions
• --mcp - Configure .mcp.json with MCP server entries
• --slash-commands - Copy slash command templates to .claude/commands/

MCP Server Configuration

The setup command adds entries to .mcp.json like:

{
  "mcpServers": {
    "cc-devtools-kanban": {
      "command": "node",
      "args": ["./node_modules/@shaenchen/cc-devtools/dist/kanban/mcp-server/index.js"],
      "disabled": false
    },
    "cc-devtools-memory": {
      "command": "node",
      "args": ["./node_modules/@shaenchen/cc-devtools/dist/memory/mcp-server/index.js"],
      "disabled": false
    }
  }
}

You can manually edit .mcp.json to:

• Disable specific tools (set "disabled": true)
• Change server names
• Adjust configuration

Data Management

Storage Locations

Each tool stores data in predictable locations:

• Kanban: cc-devtools/kanban.yaml
• Memory: cc-devtools/memory.yaml
• Planner: cc-devtools/plans/*.yaml
• Source Code Mapper: cc-devtools/.cache/source-code-index.msgpack
• Documentation Indexer: cc-devtools/.cache/documentation-index.msgpack

Gitignore

The setup command adds these patterns to .gitignore:

# cc-devtools cache
cc-devtools/.cache

You should commit cc-devtools/kanban.yaml, cc-devtools/memory.yaml, and cc-devtools/plans/ to version control to preserve project data.

Backup and Migration

To backup or migrate your data:

1. Copy the entire cc-devtools/ directory
2. Install @shaenchen/cc-devtools in the new project: npm install @shaenchen/cc-devtools
3. Run npx cc-devtools setup with desired features
4. Copy your backed-up cc-devtools/ directory to the new project

Troubleshooting

MCP Servers Not Appearing in Claude Code

1. Verify the package is installed locally: npm list @shaenchen/cc-devtools
2. Check that .mcp.json exists and is valid JSON
3. Verify that "disabled": false for each server
4. Ensure paths point to ./node_modules/@shaenchen/cc-devtools/dist/...
5. Restart Claude Code
6. Check Claude Code logs for MCP server errors

"Cannot find module" Errors

If MCP servers fail to start with module errors:

1. Verify local installation: npm list @shaenchen/cc-devtools
2. Re-install if needed: npm install @shaenchen/cc-devtools
3. Rebuild the package: npm run build (if developing locally)
4. Check that node_modules/@shaenchen/cc-devtools/dist/ exists

Tool Commands Not Working

1. Ensure the package is installed locally: npm list @shaenchen/cc-devtools
2. Check that data files exist in cc-devtools/
3. Verify file permissions on cc-devtools/ directory
4. Check for file locking issues (multiple processes)

Build Issues

If you encounter build issues during development:

# Clean and rebuild
npm run clean
npm run build

# Verify TypeScript compilation
npx tsc --noEmit

Data Corruption

If data files become corrupted:

1. Check YAML syntax with a validator
2. Restore from git history if committed
3. Review Claude Code logs for error details
4. Create a minimal test case and report as an issue

Development

Prerequisites

• Node.js >= 18.0.0
• npm or yarn
• TypeScript 5.x

Building from Source

# Clone the repository
git clone https://github.com/shaenchen/cc-devtools.git
cd cc-devtools

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# View test UI
npm run test:ui

# Generate coverage report
npm run test:coverage

Testing

The project includes comprehensive test coverage:

• 427 tests covering all tools
• Unit tests for business logic
• Integration tests for storage and file operations
• Test helpers for creating fixtures and mocking

Run tests with:

npm test                  # Run all tests once
npm run test:watch        # Watch mode
npm run test:ui           # Interactive UI
npm run test:coverage     # Coverage report

Project Structure

cc-devtools/
├── src/
│   ├── cli/              # CLI entry point and utilities
│   ├── setup/            # Setup command implementation
│   ├── kanban/           # Kanban tool
│   │   ├── lib/          # Core business logic
│   │   └── mcp-server/   # MCP server
│   ├── memory/           # Memory tool
│   ├── planner/          # Planner tool
│   └── source-code-mapper/  # Source code mapper tool
├── tests/
│   ├── integration/      # Integration tests
│   └── unit/             # Unit tests
├── templates/            # Slash command templates
└── docs/                 # Tool-specific documentation

CLI Commands Reference

Full list of available commands:

cc-devtools v0.1.0

A modular developer toolkit for Claude Code

Usage:
  npx cc-devtools <command> [options]

Commands:
  setup                       Setup cc-devtools in the current project
  status                      Show current configuration status
  add-feature                 Enable additional features
  remove-feature              Disable features
  suggest-output-style        Generate output-style suggestions for enabled features
  scm                         Source code mapper - manage code indexing and statistics
  kanban                      Kanban project management commands
  workflow                    Automated workflow state machine and code review
  web                         Start web interface for kanban and code editing
  per-file-runner             Run commands on files matching glob patterns with state tracking
  help                        Show this help message
  version                     Show version number

Examples:
  npx cc-devtools setup
  npx cc-devtools setup --features=kanban,memory
  npx cc-devtools status
  npx cc-devtools add-feature
  npx cc-devtools add-feature --features=planner
  npx cc-devtools remove-feature --features=memory --keep-data
  npx cc-devtools suggest-output-style
  npx cc-devtools scm install
  npx cc-devtools scm install rust go python
  npx cc-devtools scm list
  npx cc-devtools scm stats
  npx cc-devtools kanban list
  npx cc-devtools kanban get MVP-001
  npx cc-devtools workflow check
  npx cc-devtools workflow review
  npx cc-devtools workflow review claude codex
  npx cc-devtools web
  npx cc-devtools web --port 8080
  npx cc-devtools per-file-runner run my-config
  npx cc-devtools per-file-runner run-all
  npx cc-devtools per-file-runner automatic

For detailed documentation on specific commands, see the relevant sections above or run npx cc-devtools <command> --help.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Ensure all tests pass (npm test)
5. Submit a pull request

Code Quality Standards

• No any types - use proper TypeScript types
• Prefer interfaces over inline types
• Resolve all linting and type errors
• Add tests for new functionality
• Follow existing code style and patterns

License

MIT License - see LICENSE file for details

Support

• Issues: GitHub Issues
• Documentation: docs/
• Claude Code: https://claude.com/claude-code

Changelog

See CHANGELOG.md for version history and migration notes.

Acknowledgments

Built for use with Claude Code by Anthropic.

Uses the Model Context Protocol (MCP) for Claude Code integration.