claude-capsule-kit

A toolkit that makes Claude Code better at engineering.

Session memory. Dependency analysis. Large file navigation. 18 specialist agents.
Crew teams for parallel multi-branch work. All automatic, zero configuration.

Install

npm install -g claude-capsule-kit
cck setup

Restart Claude Code. Everything activates automatically via hooks.

Why CCK

Claude Code is powerful out of the box. But on real codebases, you run into limits:

• Session isolation — Claude starts fresh every time. Previous context, discoveries, and decisions are lost.
• No dependency awareness — Claude doesn't know your import graph. It can't tell you what breaks when you change a file.
• Large file blindness — Files over 50KB get truncated. Claude can't navigate framework internals or generated code.
• Single-threaded work — One branch, one task at a time. No way to parallelize across features.
• Agent amnesia — Sub-agents start with zero context. Findings from one agent don't flow to others.

CCK fills these gaps with a set of tools, hooks, and agents that plug into Claude Code's extension system. Nothing is patched or hacked — it's all built on official hooks, skills, commands, and agent routing.

What's in the kit

Session Memory

Hooks capture every file read, edit, and agent invocation into a local SQLite database powered by blink-query — a DNS-inspired knowledge resolution layer built for AI agents.

No manual logging. No /save commands. It just works.

cck stats overview    # See what's been captured

Dependency Tools

Claude Code doesn't know your import graph. CCK builds one.

These use a pre-built dependency graph (via the Go-based dependency-scanner) — instant results instead of Claude scanning files one by one. The Pre-Tool-Use hook automatically suggests the right tool when Claude reaches for a file.

cck build    # Build Go binaries (dependency-scanner, progressive-reader)

Large File Navigation

Files over 50KB hit Claude Code's token limit. CCK's progressive-reader parses the AST and splits files into navigable chunks — functions, classes, sections.

# Claude uses this automatically when it hits a large file
progressive-reader --path src/huge-file.ts --list     # See structure
progressive-reader --path src/huge-file.ts --chunk 3   # Read specific section

Supports TypeScript, JavaScript, Python, and Go. 75-97% token savings on large files.

18 Specialist Agents

Fresh-context agents routed by task type. All read-only — they investigate and report, never modify code.

Skills

Auto-trigger on keywords. No need to remember commands.

Crew Teams

Parallel agent teams where each teammate works on their own git branch via worktrees.

/crew-setup    # Check readiness
/crew          # Launch and coordinate a team

Define teams in .crew-config.json:

{
  "team": {
    "name": "my-feature",
    "teammates": [
      { "name": "backend", "branch": "feat/api", "role": "developer", "focus": "Build REST API" },
      { "name": "frontend", "branch": "feat/ui", "role": "developer", "focus": "Build React UI" }
    ]
  },
  "project": { "main_branch": "main" }
}

For larger teams, group teammates into crews:

{
  "team": {
    "name": "v2-release",
    "crews": [
      {
        "name": "frontend",
        "teammates": [
          { "name": "ui-dev", "branch": "feat/ui", "role": "developer", "focus": "React components" }
        ]
      },
      {
        "name": "backend",
        "teammates": [
          { "name": "api-dev", "branch": "feat/api", "role": "developer", "focus": "REST endpoints" }
        ]
      }
    ]
  }
}

Use --crew <name> to scope commands to a crew group (e.g. cck crew merge --crew frontend).

Roles: developer (sonnet, auto-commit) | reviewer (sonnet, read-only) | tester (haiku, auto-commit) | architect (opus, read-only)

What crew teams give you:

• Merge preview — dry-run conflict detection before merging branches back
• Merge execution — ordered merge with backup tags and optional test runs
• Health monitoring — detect crashed or hung teammates
• Activity monitor — real-time file ops per teammate, overlap detection
• Task decomposition — dependency-aware splitting for optimal parallelization
• Discovery sharing — teammates share findings via shared namespace in capsule.db
• Session continuity — handoff docs saved before auto-compact and at session end
• Worktree GC — clean up orphaned worktrees from past sessions

How it works

CCK extends Claude Code through its official hook system. Twelve hooks run at key moments:

SessionStart   → Restore previous context, inject discoveries, detect crew membership
PostToolUse    → Capture file ops and agent results to capsule.db
PreToolUse     → Enforce dependency tools, block large file reads, suggest right tool
PreCompact     → Save session continuity doc before context window compacts
PostCompact    → Re-inject saved context after compaction
SessionEnd     → Save session summary with branch, file count, agent count
SubagentStart  → Inject crew context and discoveries into subagent sessions
TeammateIdle   → Save teammate state and capture handoff on idle
WorktreeLifecycle → Register/deregister worktrees, update crew state
StopFailure    → Capture failure context and diagnostics for next session
Stop           → Quality check after responses

All data lives in ~/.claude/capsule.db — a SQLite database managed by blink-query, a resolution engine that organizes knowledge into namespaces with types, tags, and relationships. One global install, automatic project scoping.

Wikilink graph: prose summaries (handoffs, decisions, agent findings) are scanned for [[refs]] on save. Resolved references auto-create project-scoped ALIAS records, traversable via context-query backlinks <title-or-path> — returning hard links and FTS soft mentions. Resolution is eager-only.

CLI

cck setup              Install hooks, tools, and context system
cck teardown           Remove CCK (keeps your data)
cck update             Re-install if version changed
cck status             Show what's installed
cck build              Build Go binaries (dependency-scanner, progressive-reader)
cck stats <cmd>        Usage analytics (overview|files|agents|sessions|branch)
cck prune [days]       Clean old records (default: 30 days)

cck crew init          Create .crew-config.json
cck crew start         Launch team (setup worktrees, generate lead prompt)
cck crew stop          Stop team (removes worktrees by default)
cck crew status        Show team state
cck crew doctor        Check teammate health
cck crew activity      Show recent file ops and overlaps
cck crew merge-preview Preview branch merges (conflict detection)
cck crew merge         Execute branch merges
cck crew decompose     Analyze deps and suggest crew config
cck crew discoveries   List shared team discoveries
cck crew gc            Clean up orphaned worktrees

Requirements

• Node.js 18+
• Claude Code with hooks support
• Git (for session tracking and crew teams)
• Go 1.20+ (optional — for dependency scanner and progressive reader, install later with cck build)

For crew teams, enable Agent Teams in Claude Code settings.

Acknowledgements

CCK is built on top of Anthropic's Claude Code extension system — hooks, skills, commands, and sub-agents. None of this would work without their platform.

• blink-query — DNS-inspired knowledge resolution for AI agents. Powers capsule.db storage, namespacing, and resolution.

Uninstall

cck teardown
npm uninstall -g claude-capsule-kit

Your data (~/.claude/capsule.db) is preserved.

License

MIT - Arpit Nath

Report Bug · Request Feature