Claude Toolkit

Professional AI coding toolkit — tech-debt scanner, git worktree parallelization, and agent skills for PR review, evals, code graphs, and Fable 5.1 delegation

Two essential tools that supercharge AI-powered development workflows. Works with Claude Code, Cursor, Codex, or any AI coding assistant.

Automated code quality detection that finds:

• 📋 Duplicated code patterns
• 💀 Dead/unreachable code
• 📝 TODO/FIXME/HACK markers
• 🔒 Type safety gaps (TypeScript)
• 📦 Dependency hygiene
• 📏 File size violations

Perfect for: End-of-session cleanup, PR reviews, CI/CD quality gates

Create parallel development environments without branch-switching chaos:

• 🚀 Isolated contexts for multi-tasking
• 🤖 Perfect for parallel AI agents
• 🔄 No rebuild thrashing
• 🧠 Preserve mental context

Perfect for: Multi-agent workflows, parallel features, bug fixes while developing

# Run directly with npx (no install)
npx @unisone/claude-toolkit techdebt

# Or install globally
npm install -g @unisone/claude-toolkit

# Or clone and use directly
git clone https://github.com/unisone/claude-toolkit
cd claude-toolkit
npm link

# Scan current directory
techdebt

# Scan specific project
techdebt /path/to/project

# Auto-fix safe issues (unused imports, formatting)
techdebt --fix

# Summary only
techdebt --summary

# Generate markdown report
npx @unisone/claude-toolkit techdebt > techdebt-report.md

Example output:

CRITICAL (must fix before merge)
---------------------------------
[FILE_SIZE] src/Dashboard.tsx (547 lines)
  → Split into smaller components

[DUPLICATE] src/utils/validator.ts:45-67
  → Extract to shared utility

HIGH (fix this sprint)
----------------------
[TYPE_GAP] src/models/user.ts:34
  Function missing return type
  → Add explicit return type

SUMMARY
-------
Critical: 2
High: 3
Medium: 7
Low: 4
Total: 16 issues

# Create parallel worktrees
worktrees /path/to/repo

# Custom worktree names
worktrees /path/to/repo backend frontend testing

# Creates structure:
#   repo/              # Main (read-only)
#   repo-backend/      # Worktree 1
#   repo-frontend/     # Worktree 2
#   repo-testing/      # Worktree 3

Then navigate with shell aliases:

alias za='cd ~/Projects/repo-backend'
alias zb='cd ~/Projects/repo-frontend'
alias zc='cd ~/Projects/repo-testing'

# Jump between worktrees instantly
za  # → backend work
zb  # → frontend work (in parallel!)

Cleanup when done:

# Scripts also available directly
./scripts/worktrees/teardown-worktrees.sh /path/to/repo

Drop any skill into your Claude workspace:

# Techdebt scanner — end-of-session code quality pass
cp skills/techdebt/SKILL.md ~/.claude/skills/techdebt.md

# PR review — senior-engineer-quality pull request reviews
cp skills/pr-review/SKILL.md ~/.claude/skills/pr-review.md

# Agent evals — eval suites with LLM-as-judge rubrics for prompts and agents
cp skills/agent-evals/SKILL.md ~/.claude/skills/agent-evals.md

# Code graph — build and query a knowledge graph of your codebase
cp skills/code-graph/SKILL.md ~/.claude/skills/code-graph.md

# Fable delegation — long-running autonomous workstreams with Claude Fable 5.1
cp skills/fable-delegation/SKILL.md ~/.claude/skills/fable-delegation.md

# Or symlink for auto-updates
ln -s $(pwd)/skills/techdebt/SKILL.md ~/.claude/skills/techdebt.md

Use worktrees to run multiple Claude agents in parallel without conflicts:

# Setup parallel worktrees
worktrees ~/Projects/my-app agent-refactor agent-tests agent-docs

# Spawn sub-agents, each in their own worktree
claude spawn --label refactor --workdir ~/Projects/my-app-agent-refactor
claude spawn --label tests --workdir ~/Projects/my-app-agent-tests  
claude spawn --label docs --workdir ~/Projects/my-app-agent-docs

Each agent works in isolation. No file conflicts. Clean merges.

Create .techdebt.json in your project root:

{
  "fileSize": {
    "warning": 300,
    "critical": 500
  },
  "functionSize": {
    "warning": 50,
    "critical": 100
  },
  "duplicateThreshold": 10,
  "excludePaths": [
    "node_modules",
    "dist",
    "build"
  ],
  "autoFix": {
    "unusedImports": true,
    "formatting": false
  }
}

GitHub Actions:

name: Code Quality
on: [pull_request]

jobs:
  techdebt:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npx @unisone/claude-toolkit techdebt

Pre-commit hook:

#!/bin/bash
# .git/hooks/pre-commit
npx @unisone/claude-toolkit techdebt --summary

AI assistants ship fast. Quality control can't keep up.

When you have Claude, Cursor, or Codex generating thousands of lines per session:

• Technical debt accumulates faster than humans can review
• Parallel agents create branch chaos (Agent A conflicts with Agent B)
• Context switching kills productivity (branch checkout = rebuild = 5min lost)
• Type safety erodes (any types slip through, @ts-ignore proliferates)
• Dead code piles up (commented blocks, failed experiments)

This toolkit solves both problems: automated quality checks + conflict-free parallelization.

Worktrees are becoming the standard for AI-native development:

• Codex macOS app — Uses worktrees for multi-agent orchestration
• AirOps — Built worktree-cli for parallel agent workflows
• Medium articles — Growing coverage of worktree patterns for AI coding
• Boris Cherny (2019) — Pioneered parallel worktree development

Why now? AI agents made parallelization essential. Traditional branch-switching workflows break when you have:

• 3 agents refactoring different modules simultaneously
• Production hotfix needed while feature branch is mid-build
• Experimental refactor running alongside stable development

Git worktrees solve this. This toolkit makes them trivial to use.

When to use what:

• claude-toolkit — Daily AI coding workflows, fast feedback, zero setup
• SonarQube — Enterprise CI/CD, compliance requirements, multi-repo dashboards
• ESLint — JavaScript/TypeScript linting, strict style enforcement
• GitHub Advanced Security — Security vulnerability scanning, enterprise compliance

Combine them! Use claude-toolkit for fast local checks, ESLint for style, SonarQube for team dashboards.

1. Post-session cleanup — Run techdebt --fix after Claude builds features
2. Parallel bug fixing — Fix prod issues in worktree B while building in worktree A
3. Multi-agent refactoring — Spawn 3 agents in 3 worktrees, merge when done
4. PR quality gates — Fail CI if critical techdebt detected
5. Code archaeology — Use analysis worktree for safe exploration
6. A/B implementation testing — Try two approaches in parallel worktrees, keep the best

• Techdebt Scanner: skills/techdebt/SKILL.md
• Worktree Manager: scripts/worktrees/README.md
• CLI Help: Run techdebt --help or worktrees --help

• Node.js: >=18
• Git: 2.20+ (for worktrees)
• Bash: 4.0+ (macOS/Linux)

Optional (enhanced features):

• eslint — Auto-fix linting issues
• prettier — Auto-format code
• jq — JSON parsing for advanced features

Contributions welcome! This is a community-driven toolkit.

See CONTRIBUTING.md for:

• Development workflow
• Conventional commit guidelines
• Testing procedures
• High-priority contribution areas

Quick start:

# Fork and clone
git clone https://github.com/unisone/claude-toolkit
cd claude-toolkit

# Make changes
git checkout -b feat/my-feature

# Test using dogfooding!
./skills/techdebt/scripts/scan.sh
./skills/techdebt/scripts/scan.sh --fix

# Commit and PR
git commit -m "feat: add Python support"
git push origin feat/my-feature

• README.md — Main documentation (this file)
• CONTRIBUTING.md — Contribution guidelines
• CHANGELOG.md — Release history
• examples/ — Usage examples and patterns
  • CI Integration
  • Worktree Patterns
  • Sample Output
• Skills:
  • Techdebt Scanner
  • Worktree Manager

MIT © Alex Zay

See LICENSE for full text.

Built for the AI coding era. Maintained by humans (for now).

Questions? Open an issue or find me on X/Twitter.