GitHub - arpitnath/super-claude-kit: Transform Claude Code from stateless to stateful. Persistent context memory system with cross-session persistence, token-efficient storage, and zero dependencies.

Claude Capsule Kit adds persistent memory to Claude Code.

A persistence layer for Claude Code.
Files, tasks, discoveries — all restored instantly.

curl -fsSL https://raw.githubusercontent.com/arpitnath/super-claude-kit/master/install | bash

📍 Per-project installation — Run from your project root, installs to .claude/
Works alongside vanilla Claude Code (enhancement, not replacement)

Quickstart

Installing Claude Capsule Kit

Run the one-line installer from your project root:

cd your-project
curl -fsSL https://raw.githubusercontent.com/arpitnath/super-claude-kit/master/install | bash

Note: This installs to your project's .claude/ directory (like .claude/settings.json). Install separately in each project where you want Claude Capsule Kit features. This is not a global installation — it enhances Claude Code per-project.

That's it! Restart Claude Code and you'll see the context capsule on every session.

Manual installation (advanced)

# Clone to your project directory
cd your-project
git clone https://github.com/arpitnath/super-claude-kit.git .super-claude-kit-src
cd .super-claude-kit-src

# Run the installer (installs to parent project)
bash install

The installer will:

Install hooks to .claude/hooks/
Build Go tools (dependency-scanner, progressive-reader)
Configure .claude/settings.local.json
Auto-install Go 1.23+ if not present

What you get immediately

After installation, Claude Code will:

🧠 Remember files you've accessed (no re-reads)
📦 Restore context between sessions (up to 24 hours)
✅ Track tasks across restarts
🔍 Log discoveries as you work
🔗 Understand dependencies in your codebase

How it works

Claude Capsule Kit uses hooks (SessionStart, UserPromptSubmit) to:

Capture context as you work (file access, tasks, git state)
Store in capsule (.claude/capsule.json)
Restore on restart (automatic, zero manual input)

No configuration needed. It just works.

Features

🧠 Persistent Memory

Stop wasting tokens on re-reads.

Vanilla Claude Code re-reads files on every question. Claude Capsule Kit tracks what's been read and references from memory.

📦 Context Capsule

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 CONTEXT CAPSULE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🌿 Git State:
   Branch: feat/oauth (2 commits ahead)

📁 Files in Context:
   • auth/OAuthController.ts (read 2h ago)
   • config/google.ts (edited 1h ago)
   • routes/auth.ts (read 2h ago)

🔍 Discoveries:
   • Google OAuth requires state parameter
   • Token stored in httpOnly cookie

✅ Current Tasks:
   ⚡ Implementing OAuth callback handler
   ✓ Controller setup complete
   ✓ Google provider config added

💡 Previous session: 2 hours ago
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

See exactly what Claude remembers. Every session start shows your capsule with:

Git branch and commit status
Files accessed with timestamps
Discoveries logged during work
Active and completed tasks
Time since last session

The capsule uses TOON format for 52% token reduction compared to JSON.

🧠 Memory Graph

Understand relationships, not just files.

Memory Graph tracks semantic connections between files, functions, decisions, and tasks as you work.

# Visualize the graph
/memory-graph

Auto-linking while you work:

Read a file → Creates node
Edit imports → Links dependencies
Complete task → Updates relationships
Make decision → Links to affected files

Query the graph:

"What depends on this file?" → Instant traversal
"Why did we choose X?" → Decision nodes with context
"What breaks if I change this?" → Impact via relationships

🔗 Dependency Intelligence

Know what breaks before you break it.

Built-in dependency scanner analyzes your codebase:

Available Commands

# Query what files import this file
.claude/tools/query-deps/query-deps.sh src/auth.ts

# Analyze impact of changing a file
.claude/tools/impact-analysis/impact-analysis.sh src/database.ts

# Find circular dependencies
.claude/tools/find-circular/find-circular.sh

# Identify unused files
.claude/tools/find-dead-code/find-dead-code.sh

Performance

1,000 files scanned in <5 seconds
10,000 files scanned in <30 seconds
Supports TypeScript, JavaScript, Python, Go

📊 Progressive Reader Demo

See the difference when working with large files (187KB React source):

full_final.mp4

Metric	Vanilla Claude Code	Claude Capsule Kit
Initial Read	`MaxFileReadTokenExceededError`	Same error
Recovery	8+ Read calls with offset/limit	Uses progressive-reader
Lines read	5,339 lines (guessing)	100 lines (targeted)
Token savings	—	98% for structure

🧪 Try it yourself

# 1. Clone React and install Claude Capsule Kit
git clone https://github.com/facebook/react.git && cd react
curl -fsSL https://raw.githubusercontent.com/arpitnath/super-claude-kit/master/install | bash

# 2. Run Claude Code in debug mode
claude --debug

# 3. Send this prompt:
# "Summarize all functions in ReactFiberWorkLoop.js, organized by category"

What to look for:

Vanilla: 8+ Read operations with arbitrary 800-line chunks
Claude Capsule Kit: progressive-reader --list → targeted chunk reads

🛠️ Built-in Tools

Progressive Reader

Read large files (>50KB) in semantic chunks using tree-sitter AST parsing.

# Read first chunk of a large file
progressive-reader --path src/large-file.ts

# List all chunks without content (preview)
progressive-reader --list --path src/large-file.ts

# Read specific chunk by index
progressive-reader --chunk 2 --path src/large-file.ts

# Continue from previous read (uses TOON token)
progressive-reader --continue-file /tmp/continue.toon

Supported languages: TypeScript, JavaScript, Python, Go

When to use:

Files > 50KB that would consume too much context
Reading sub-agent outputs progressively
Large codebase exploration with minimal context usage

Dependency Scanner

Analyzes code structure and relationships using tree-sitter AST parsing.

# Build dependency graph
~/.claude/bin/dependency-scanner --path . --output .claude/dep-graph.toon

Features:

Import/export tracking
Circular dependency detection (Tarjan's algorithm)
Impact analysis
Dead code identification

🤖 Specialized Sub-Agents

Production-safe, read-only agents for common development tasks:

architecture-explorer - Understand service boundaries and data flows
database-navigator - Explore schemas, migrations, and relationships
agent-developer - Build and debug AI agents with MCP integration
github-issue-tracker - Create well-formatted issues from discoveries

All agents are sandboxed and require explicit permission for write operations.

Docs & Guides

Requirements

Claude Code (Desktop CLI or VSCode extension)
macOS or Linux (Windows WSL supported)
Go 1.23+ (auto-installed if not present)
Bash 4.0+

Optional (for enhanced features):

Git - Provides branch tracking and git-aware change detection
- Without git: Uses file modification time for change detection
- All core features work without git

Verification

After installation, verify everything works:

# Run comprehensive tests
bash .claude/scripts/test-super-claude.sh

# View current stats
bash .claude/scripts/show-stats.sh

# Check installed tools
~/.claude/bin/dependency-scanner --version
~/.claude/bin/progressive-reader --version

Expected output:

✅ Claude Capsule Kit v1.0.0
✅ dependency-scanner v1.0.0
✅ progressive-reader v1.0.0
✅ All hooks configured
✅ All tests passed

Updating

Check for Updates

bash .claude/scripts/update-super-claude.sh

Development Mode

Install latest development version:

bash .claude/scripts/update-super-claude.sh --dev

Configuration

Settings Location

.claude/settings.local.json

{
  "permissions": {
    "allow": [
      "Bash(git add:*)",
      "Bash(git commit:*)",
      "Bash(~/.claude/bin/dependency-scanner:*)",
      "Bash(progressive-reader:*)"
    ]
  },
  "hooks": {
    "SessionStart": ["bash .claude/hooks/session-start.sh"],
    "UserPromptSubmit": ["bash .claude/hooks/pre-task-analysis.sh"]
  }
}

Customization

Custom hooks - Add to hooks/ directory
Custom tools - Add to tools/ directory
Specialized agents - Add to agents/ directory
Reusable skills - Add to skills/ directory

See Configuration Guide for details.

Troubleshooting

Hooks not executing

# Verify settings
cat .claude/settings.local.json

# Test hook manually
bash .claude/hooks/session-start.sh

Capsule not updating

# Force refresh
rm .claude/last_refresh_state.txt

# Check logs
tail -f .claude/hooks.log

Dependency graph not building

# Verify scanner installation
ls -la ~/.claude/bin/dependency-scanner

# Rebuild manually
~/.claude/bin/dependency-scanner --path . --output .claude/dep-graph.toon

Debug Mode

Enable verbose logging:

CLAUDE_DEBUG_HOOKS=true claude

For more issues, see FAQ or open an issue.

Common Questions

Q: Do I install this globally or per-project? A: Per-project. Run the install script from each project where you want Claude Capsule Kit. It installs to .claude/ in that directory.

Q: Does this replace Claude Code? A: No. It enhances Claude Code by adding hooks, tools, and persistent context memory. You still use the normal claude command.

Q: Where are files installed? A: In your project's .claude/ directory: hooks, tools, bin, settings. Similar to how .claude/settings.json works.

Q: Can I use it in multiple projects? A: Yes! Install separately in each project. Each project gets its own context capsule and dependency graph.

Performance

Benchmarks

Operation	Performance	Details
Context Refresh	<100ms	Smart change detection
Graph Building	1000 files in <5s	Parallel parsing
Large Project	10000 files in <30s	Incremental updates
Token Efficiency	~52% reduction	TOON vs JSON and avoids re-reads

Uninstall

cd super-claude-kit
bash uninstall

Removes hooks, tools, and configuration. Your .claude/ data logs are preserved in .claude/backup/.

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes with clear messages
Push to branch (git push origin feature/amazing-feature)
Open a pull request

See CONTRIBUTING.md for detailed guidelines.

Development Setup

git clone https://github.com/arpitnath/super-claude-kit.git
cd super-claude-kit
bash install

Running Tests

bash .claude/scripts/test-super-claude.sh

License

This repository is licensed under the MIT License.

Acknowledgments

Anthropic - Claude and Claude Code
TOON Format - Token-Oriented Object Notation
Tree-sitter - Incremental parsing system

Star History

If you found Claude Capsule Kit useful, please star the repo! ⭐

Never re-explain yourself to Claude. Ever.

Report Bug · Request Feature · GitHub · LinkedIn

Name		Name	Last commit message	Last commit date
Latest commit History 74 Commits
.github		.github
agents		agents
commands		commands
docs		docs
hooks		hooks
lib		lib
scripts		scripts
skills		skills
tools		tools
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CLAUDE_TEMPLATE.md		CLAUDE_TEMPLATE.md
README.md		README.md
install		install
manifest.json		manifest.json

arpitnath/super-claude-kit

Folders and files

Latest commit

History

Repository files navigation

Quickstart

Installing Claude Capsule Kit

What you get immediately

How it works

Features

🧠 Persistent Memory

📦 Context Capsule

🧠 Memory Graph

🔗 Dependency Intelligence

Available Commands

Performance

📊 Progressive Reader Demo

🛠️ Built-in Tools

Progressive Reader

Dependency Scanner

🤖 Specialized Sub-Agents

Docs & Guides

Requirements

Verification

Updating

Check for Updates

Development Mode

Configuration

Settings Location

Customization

Troubleshooting

Hooks not executing

Capsule not updating

Dependency graph not building

Debug Mode

Common Questions

Performance

Benchmarks

Uninstall

Contributing

Development Setup

Running Tests

License

Acknowledgments

Star History

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 7

Contributors 3

Uh oh!

Languages