Context Tools for Claude Code

A Claude Code plugin that helps Claude maintain context awareness in large codebases through automatic project mapping, duplicate detection, and learning retention.

Features

Project Manifest

Automatically detects and tracks:

• Programming languages in your project
• Build system and commands (npm, uv, pdm, cargo, cmake, meson, go)
• Entry points and main scripts
• Git activity summary

Repository Map with Duplicate Detection

Generates a comprehensive map of your codebase:

• Multi-language support: Python, C++, and Rust
• Extracts all classes, functions, and methods with their signatures
• Detects potentially similar classes that may have overlapping responsibilities
• Identifies similar functions that could be candidates for consolidation
• Analyzes documentation coverage to highlight gaps
• Incremental caching: Only re-parses changed files (mtime + content hash)
• Parallel parsing: Uses multiple CPU cores for large codebases
• Background execution: Repo map builds asynchronously on session start

Learnings System

Helps Claude remember important discoveries:

• Project-specific learnings in .claude/learnings.md
• Global learnings in ~/.claude/learnings.md
• Prompted to save learnings before context compaction

Installation

Option 1: Install from GitHub (recommended)

First, add the repository as a plugin marketplace:

claude plugin marketplace add chipflow/claude-context-tools

Then install the plugin:

claude plugin install context-tools

Option 2: Install from local directory (for development)

git clone https://github.com/chipflow/claude-context-tools.git
claude plugin marketplace add ./claude-context-tools
claude plugin install context-tools

Option 3: Load directly without installing

For testing or one-off use:

claude --plugin-dir ./claude-context-tools

Requirements

• uv - Python package manager (for running scripts)
• Python 3.10+

How It Works

Hooks

The plugin registers two hooks:

1. SessionStart: When you start a Claude Code session, the plugin:

   • Generates/refreshes the project manifest
   • Displays a summary of project context
   • Shows count of available learnings

2. PreCompact: Before context compaction, the plugin:

   • Regenerates the project manifest
   • Updates the repository map
   • Reminds you to save important discoveries

Slash Commands

• /context-tools:repo-map - Regenerate the repository map
• /context-tools:manifest - Regenerate the project manifest
• /context-tools:learnings - View and manage project learnings

Configuration

Repo Map Options

The repo map generator supports command-line options:

# Use 75% of CPU cores for parsing (default: 50%)
uv run scripts/generate-repo-map.py /path/to/project --workers=75

Supported Languages

Language	Extensions	Parser
Python	.py	Built-in AST
C++	.cpp, .cc, .cxx, .hpp, .h, .hxx	tree-sitter-cpp
Rust	.rs	tree-sitter-rust

Generated Files

The plugin creates files in your project's .claude/ directory:

.claude/
├── project-manifest.json   # Build system, languages, entry points
├── repo-map.md             # Code structure with similarity analysis
├── repo-map-cache.json     # Symbol cache for incremental updates
└── learnings.md            # Project-specific learnings

Example Output

Repository Map

## Documentation Coverage

- **Classes**: 15/18 (83% documented)
- **Functions**: 42/50 (84% documented)

## ⚠️ Potentially Similar Classes

- **ConfigLoader** (src/config/loader.py)
  ↔ **SettingsLoader** (src/settings/loader.py)
  Reason: similar names (80%), similar docstrings (72%)

## Code Structure

### src/models/user.py

**class User**
  A user account in the system.
  - create(name: str, email: str) -> User
      Create a new user account.
  - update(self, **kwargs)
      Update user attributes.

Project Manifest

{
  "project_name": "my-project",
  "languages": ["python", "typescript"],
  "build_system": {
    "type": "uv",
    "commands": {
      "install": "uv sync",
      "build": "uv run build",
      "test": "uv run pytest"
    }
  },
  "entry_points": ["src/main.py", "src/cli.py"]
}

Best Practices

Recording Learnings

When you discover something important during a session, ask Claude to record it:

"Add a learning about the database connection pooling optimization we just discovered"

Claude will add an entry to .claude/learnings.md:

## Database: Connection pooling optimization

**Context**: High-traffic API endpoints with PostgreSQL
**Discovery**: Default pool size of 5 was causing connection exhaustion
**Solution/Pattern**: Increase pool size to 20, add 30s timeout, implement retry with exponential backoff

Addressing Duplicate Detection

When the repo map shows similar classes or functions:

1. Review the flagged pairs to determine if they're truly duplicates
2. If they serve different purposes, improve their docstrings to clarify intent
3. If they're duplicates, consolidate them into a single implementation

Development

Running Tests Locally

# Validate JSON configs
python3 -c "import json; json.load(open('.claude-plugin/plugin.json'))"
python3 -c "import json; json.load(open('hooks/hooks.json'))"

# Check bash script syntax
bash -n scripts/session-start.sh
bash -n scripts/precompact.sh

# Test repo map generation
mkdir -p /tmp/test-project
echo 'def hello(): pass' > /tmp/test-project/main.py
uv run scripts/generate-repo-map.py /tmp/test-project

Adding Language Support

To add support for a new language:

1. Add the tree-sitter grammar to dependencies in generate-repo-map.py
2. Create an extract_symbols_from_<lang>() function
3. Add file discovery in find_<lang>_files()
4. Update parse_file_worker() to handle the new language
5. Add tests in the CI workflow

License

MIT