ctx-pilot

AI that knows your codebase.

Works with Claude Code, Gemini CLI, Cursor, Windsurf, and Aider.

The Problem

You're deep in a coding session with Claude Code. You've explained your project's architecture, the key concepts, the naming conventions. Then, 10 messages later:

You: "Update the Widget component"
Claude: "I don't see a Widget component. Can you show me where it's defined?"
You: "It's in core-concepts.md, like I showed you earlier..."

Sound familiar? Context gets lost. You repeat yourself. Momentum dies.

The Solution

ctx-pilot suggests relevant files when you need them. Claude reads them and stays informed.

You: "Update the Widget component"

<ctx-pilot>
Look into these files for context:

**Pinned (always relevant):**
- docs/core-concepts.md

**Relevant to your task:**
- src/components/Widget.tsx (lines 12-45) - function Widget
- docs/components.md (lines 88-102) - Widget Props
</ctx-pilot>

Claude: "I'll update the Widget component. Based on the props defined in
        core-concepts.md, here's what I'll change..."

Zero friction. Install once, forget it exists. Context just works.

Why ctx-pilot?

• File suggestions, not content injection - Claude reads files itself, keeping you in control
• Section-aware indexing - Points to specific functions and headers, not entire files
• Smart search - Stemming and fuzzy matching find what you mean, not just what you type
• Smart skip - Stays silent when there's nothing useful to add
• Automatic indexing - Built-in parsers for 20+ languages, no AI required
• Works offline - Everything runs locally, no API keys or accounts needed
• Graceful degradation - If something breaks, your AI tool works exactly as before

If ctx-pilot saves you time, consider sponsoring the project.

Enterprise Ready

• Runs 100% locally - No data leaves your machine. No API keys. No accounts.
• Scales with your codebase - Tested on 44K+ lines across 73 files
• Team-friendly - Share indexes via git, track usage analytics
• Dual licensed - Free for most, commercial license for enterprises

Enterprise Features (v0.11.0+)

| Feature | Command | Description | |---------|---------|-------------| | Index Quality | npx ctx-pilot audit | Score your index (0-100) with recommendations | | Team Sync | npx ctx-pilot sync | Pull team's index from git | | Analytics | npx ctx-pilot stats | View usage statistics (opt-in) | | Audit Log | npx ctx-pilot audit-log | Compliance logging (opt-in) | | Semantic Search | npx ctx-pilot embed | Add AI embeddings for meaning-based search | | Multi-Repo | npx ctx-pilot link | Search across linked repositories |

All features are opt-in and run 100% locally.

Quick Start

npx ctx-pilot init

Restart your AI CLI, then ask:

Follow the instructions in .context/optimize.md

Your AI analyzes your codebase and builds an optimized index. Done - ctx-pilot now suggests relevant files before every prompt.

Alternative (instant setup): If you want to skip the AI step:

npx ctx-pilot auto-index

Built for scale. Used to manage a 44K-line documentation project with 73 files.

Free for most users. Commercial license required for companies with >$1M annual revenue.

How It Works

1. You type a prompt in Claude Code
2. ctx-pilot extracts topics from your message (function names, file paths, keywords)
3. Searches your indexed files for matching sections
4. Suggests relevant files with specific line ranges
5. Claude reads them and responds with full context

All invisible. All automatic. No commands to remember.

Who It's For

• Documentation-heavy projects - Game design docs, API specs, internal wikis
• Complex codebases - Where context matters and getting up to speed takes time
• Long coding sessions - When you need Claude to remember what you discussed
• Teams - Share pinned files so Claude understands your conventions

Installation

Requirements

• Node.js 18+
• Claude Code or Gemini CLI

Setup

npx ctx-pilot init

Restart your AI CLI, then ask: Follow the instructions in .context/optimize.md

Your AI builds an optimized, section-aware index of your codebase.

Manual Hook Install

If you need to install the hook separately:

npx ctx-pilot hook --claude   # For Claude Code
npx ctx-pilot hook --gemini   # For Gemini CLI

Configuration

Edit .context/config.json:

{
  "pinned": ["docs/core-concepts.md", "docs/glossary.md"],
  "include": ["**/*.md", "**/*.ts", "**/*.py"],
  "exclude": ["node_modules/**", "dist/**"]
}

| Field | What it does | |-------|--------------| | pinned | Files suggested on every prompt (your core docs) | | include | What to index (glob patterns) | | exclude | What to skip entirely | | minTopics | Minimum searchable terms to trigger suggestions (default: 2). Set to 0 for always-on. | | minScore | Minimum relevance score to show a result (default: 1.0). Lower = more results, higher = stricter. | | excludeFromSuggestions | Patterns to index but never suggest (e.g., ["tests/**"] to index tests for completeness but not clutter suggestions) | | domainStopwords | Common project terms to ignore in search (e.g., your app name) |

Enterprise Config Options

{
  "team": { "remote": "git", "branch": "main" },
  "analytics": { "enabled": true },
  "auditLog": { "enabled": true, "retention": "30d" },
  "suggestions": { "includeRelated": true, "maxRelated": 2 },
  "search": { "enabled": true },
  "linkedRepos": [{ "name": "shared-lib", "path": "../shared-lib" }]
}

| Field | What it does | |-------|--------------| | team | Git branch for team sync (sync/publish commands) | | analytics | Enable usage statistics collection (local only) | | auditLog | Enable compliance logging with retention period | | suggestions.includeRelated | Show related files based on imports | | search.enabled | Enable semantic search (requires embeddings) | | linkedRepos | External repositories to include in search |

Customizing for Your Project

The default config indexes markdown files only. Here's how to tailor ctx-pilot to your codebase.

Step 1: Decide What to Index

Think about what files contain useful context:

• Source code - Functions, classes, components
• Documentation - READMEs, guides, API docs
• Tests - Show expected behavior and edge cases
• Config files - Project structure and settings

Update your include patterns:

{
  "include": [
    "**/*.md",
    "src/**/*.ts",
    "tests/**/*.ts"
  ]
}

Common patterns:

• **/*.md - All markdown files
• src/**/*.ts - TypeScript in src folder
• docs/**/* - Everything in docs folder
• *.json - JSON files in root only

Step 2: Exclude Noise

Keep generated files and dependencies out:

{
  "exclude": [
    "node_modules/**",
    "dist/**",
    "build/**",
    "coverage/**",
    "*.min.js"
  ]
}

Step 3: Pin Your Core Docs

Pinned files appear in every suggestion. Use sparingly - these are your "always relevant" files:

{
  "pinned": [
    "CLAUDE.md",
    "docs/architecture.md"
  ]
}

Good candidates:

• Project overview docs
• Architecture decisions
• Coding conventions
• Glossaries

Step 4: Build the Index

Ask your AI to build the index:

Follow the instructions in .context/optimize.md

Your AI analyzes your codebase and creates a section-aware index with:

• Meaningful section titles
• Rich keywords including synonyms
• Descriptive previews explaining what code does

Alternative (quick baseline): For instant setup without AI:

npx ctx-pilot auto-index

This uses built-in parsers to extract functions, classes, and headers. Works immediately but produces more generic results.

Advanced: Domain Stopwords

If certain words appear everywhere in your project and aren't useful for search, filter them out:

{
  "pinned": ["CLAUDE.md"],
  "include": ["**/*.md", "src/**/*.ts"],
  "exclude": ["node_modules/**"],
  "domainStopwords": ["myapp", "widget", "util"]
}

Use this when common project terms are drowning out more specific matches.

Example: Full Config

Here's a complete config for a TypeScript project:

{
  "pinned": ["CLAUDE.md", "docs/architecture.md"],
  "include": [
    "**/*.md",
    "src/**/*.ts",
    "tests/**/*.ts"
  ],
  "exclude": [
    "node_modules/**",
    "dist/**",
    "coverage/**"
  ],
  "excludeFromSuggestions": ["tests/**"],
  "minTopics": 2,
  "minScore": 1.0,
  "domainStopwords": ["myproject"]
}

After saving, rebuild and verify:

npx ctx-pilot auto-index
npx ctx-pilot validate
npx ctx-pilot status

CLI Commands

Setup & Indexing

npx ctx-pilot init              # Set up config and install hook
npx ctx-pilot status            # Show config, index, hooks, and exports
npx ctx-pilot validate          # Check index for issues
npx ctx-pilot audit             # Score index quality with recommendations
npx ctx-pilot auto-index        # Build index automatically (fallback)
npx ctx-pilot auto-index -v     # Build with verbose output
npx ctx-pilot auto-index -f     # Force full rebuild (ignore cache)
npx ctx-pilot search <query>    # Test what matches a query
npx ctx-pilot watch             # Auto-rebuild on file changes

The primary way to build the index is asking your AI: Follow the instructions in .context/optimize.md

Enterprise Commands

# Team Sync
npx ctx-pilot sync              # Pull team's index from git
npx ctx-pilot publish           # Push index to team via git

# Analytics (opt-in)
npx ctx-pilot stats             # View usage statistics
npx ctx-pilot audit-log         # View suggestion history (compliance)

# Semantic Search (requires @xenova/transformers)
npx ctx-pilot embed             # Add embeddings to existing index

# Multi-Repo
npx ctx-pilot link <path>       # Link external repository
npx ctx-pilot unlink <name>     # Unlink repository
npx ctx-pilot links             # List linked repositories

Dynamic Hooks (Claude Code, Gemini CLI)

Per-prompt context suggestions - runs automatically before every message.

npx ctx-pilot hook            # Install hook (auto-detects Claude/Gemini)
npx ctx-pilot hook --claude   # Install for Claude Code
npx ctx-pilot hook --gemini   # Install for Gemini CLI

Static Exports (Cursor, Windsurf, Aider)

Generate context files for tools without hook support.

npx ctx-pilot export --cursor     # Generate .cursorrules
npx ctx-pilot export --windsurf   # Generate .windsurfrules
npx ctx-pilot export --aider      # Generate .aider.context.md
npx ctx-pilot export --mdc        # Generate .cursor/rules/ctx-pilot.mdc
npx ctx-pilot export --all        # Generate all exports

How Indexing Works

ctx-pilot uses AI-driven indexing. Your AI analyzes your codebase and builds a section-aware index:

AI Indexing (Recommended)

Follow the instructions in .context/optimize.md

Your AI:

• Understands your code semantically, not just syntactically
• Creates meaningful section titles and previews
• Adds rich keywords including synonyms and related terms
• Identifies what actually matters in your codebase

This produces the best results because your AI understands context.

Automatic Indexing (Fallback)

For instant setup without AI involvement:

npx ctx-pilot auto-index

Built-in parsers extract sections from 20+ file types:

• Markdown - Headers and code blocks
• JavaScript/TypeScript - Functions, classes, interfaces, types
• Python - Functions and classes
• Go, Rust, Java, C#, Ruby, Swift, PHP, Shell - Functions and types
• Structured data - YAML, JSON, TOML sections

This works immediately but produces more generic results (function names as titles, extracted keywords rather than curated ones).

Smart Search

ctx-pilot uses intelligent matching to find relevant sections:

• Stemming - "authentication" matches "authenticate", "auth"
• Fuzzy matching - Typos like "authentification" still match
• Weighted scoring - Title matches rank higher than keyword matches

Smart Skip

ctx-pilot stays silent when it has nothing useful to add:

• Short prompts with few searchable terms (like "thanks" or "looks good") produce no output
• Low-confidence matches are filtered out
• Only results above a relevance threshold are shown

This prevents noise - you only see suggestions when they're actually helpful.

Stale File Detection

ctx-pilot automatically detects when indexed files have changed:

**Relevant to your task:**
- src/auth.ts (lines 12-45) - function login ⚠️

⚠️ Before answering, update .context/index.json for files marked ⚠️.

Claude automatically updates the index for stale files before responding - no action needed from you.

Validation

Check your index for issues:

npx ctx-pilot validate

This checks for missing pinned files, invalid line numbers, empty keywords, and orphaned entries.

Troubleshooting

Nothing happening?

• Run npx ctx-pilot status to check setup
• Make sure you ran npx ctx-pilot auto-index
• Restart Claude Code after installing

Wrong suggestions?

• Add important files to pinned
• Adjust include/exclude patterns
• Rebuild with npx ctx-pilot auto-index
• Check for issues with npx ctx-pilot validate

Seeing ⚠️ warnings?

• Files changed since the index was built
• Claude updates the index automatically before answering
• Or rebuild manually with npx ctx-pilot auto-index

No suggestions appearing?

• This is often intentional - ctx-pilot stays silent when there's nothing useful to add
• Try prompts with specific terms (function names, file paths, technical concepts)
• Check npx ctx-pilot status to verify the hook is installed and index exists

ctx-pilot stops working?

• It fails gracefully - your AI tool works exactly as before, just without suggestions
• Check npx ctx-pilot status for diagnostics
• Reinstall the hook with npx ctx-pilot hook

Privacy

ctx-pilot runs 100% locally. No telemetry, no analytics, no network requests.

• Your code stays on your machine
• No accounts or API keys required
• Works offline
• Open source - audit the code yourself

Performance

ctx-pilot is designed to be invisible:

• Hook execution: < 100ms per prompt
• Memory: Minimal - index stored on disk

Contributing

Found a bug? Have an idea? Contributions welcome!

• Issues: Report bugs or request features
• PRs: Fork, branch, submit

See CONTRIBUTING.md for guidelines.

Support the Project

If ctx-pilot saves you time, consider supporting its development:

• ⭐ Star the repo - Helps others discover it
• 🐛 Report issues - Help make it better
• 💻 Contribute code - New features, bug fixes
• 💬 Spread the word - Tweet, blog, tell your team
• ❤️ Sponsor - GitHub Sponsors

License

Free for most users. Dual-licensed:

• MIT License - Free for individuals, education, open source, and companies with <$1M annual revenue
• Commercial License - Required for larger commercial entities

Most developers and small teams can use ctx-pilot freely under MIT. See LICENSE and LICENSE-COMMERCIAL for details.

Built by @stephen-gobin | Suite110