CodePulse – token-efficient codebase indexer for AI coding tools
CodePulse is an open-source codebase indexer that saves 60-80% of token budget for AI coding assistants by maintaining a persistent, git-diff-aware index and injecting a compact snapshot at session start. It supports Claude Code, OpenAI Codex CLI, Cursor, and other tools, with features like task-aware ranking, git-aware ranking, and auto budget. It offers CLI, MCP server, and multiple integration methods.
Article intelligence
Key points
- Saves 60-80% of exploration tokens for AI assistants via pre-built snapshots.
- Supports multiple AI tools: Claude Code, Codex CLI, Cursor, etc.
- Features: task-aware ranking, git-aware ranking, and auto token budget.
- Uses Tree-Sitter for parsing and stores index in SQLite with incremental updates.
Why it matters
This matters because saves 60-80% of exploration tokens for AI assistants via pre-built snapshots.
Technical impact
May affect model selection, inference cost, product capability, and evaluation benchmarks.
Notifications You must be signed in to change notification settings
Fork 0
Star 1
BranchesTags
Open more actions menu
Folders and files
NameName
Last commit message
Last commit date
Latest commit
History
11 Commits
11 Commits
packages
packages
skill/codepulse
skill/codepulse
.gitignore
.gitignore
CLAUDE.md
CLAUDE.md
README.md
README.md
package-lock.json
package-lock.json
package.json
package.json
tsconfig.base.json
tsconfig.base.json
vitest.config.ts
vitest.config.ts
Repository files navigation
Token-efficient codebase indexing for AI coding tools.
AI assistants waste 60–80% of their token budget exploring your repo on every new conversation. CodePulse maintains a persistent, git-diff-aware index and injects a compact snapshot — repo structure, exported symbols, import graph — at session start.
Works with Claude Code (skill), OpenAI Codex CLI (pipe or AGENTS.md), Cursor/Continue.dev (MCP server), and any tool that can consume CLI output.
Token Savings
Without CodePulse, an AI assistant typically reads 10–30 files per session just to understand your repo before it can help. With CodePulse, it gets a pre-built snapshot instead — no exploration needed.
Repo Size Without CodePulse With CodePulse Saved
Small ( Search exported symbols by name
codepulse search --limit 10 Limit results
codepulse stats Show index stats
codepulse watch Auto-update on file changes
codepulse install-hooks Install git post-commit hook for auto-updates
codepulse uninstall-hooks Remove git hooks
Smart Context
CodePulse ranks what goes into the snapshot so the most useful files fit within the budget:
Task-aware ranking — pass --task to rank files by relevance to what you're working on:
codepulse context --auto --task "fix the login bug"
Keywords are extracted from your task description and matched against file paths, symbol names, exported function signatures, and stored file summaries. Files most relevant to your task appear first.
Git-aware ranking — even without --task, CodePulse checks which files you've recently changed (git diff) and boosts those automatically. Files with a longer history of changes rank higher by default.
Auto budget — --auto scales the token budget to your repo's complexity score (symbols × 2 + imports + lines/50). Tiny repos are skipped entirely:
Complexity Budget
AGENTS.md > AGENTS.md
Run it before starting Codex:
bash scripts/codex-init.sh && codex
Codex will pick up AGENTS.md automatically on startup, giving it instant structural awareness without exploring the repo itself.
Option 3 — Always-on via shell alias:
Add to ~/.zshrc or ~/.bashrc
alias codex='(codepulse update --full 2>/dev/null; codepulse context --format markdown > /tmp/cp-context.md); codex --context /tmp/cp-context.md'
Note: --context flag availability depends on your Codex CLI version. Check codex --help for the exact flag name.
MCP Server (Cursor, Continue.dev, etc.)
Add to your MCP config:
{ "codepulse": { "command": "codepulse-mcp", "args": [] } }
Tools available:
get_context(budget_tokens, focus_path?) — full context snapshot
search_symbols(query) — find exported symbols by name
get_file_summary(path) — symbols, imports, and importers for one file
How It Works
Index: Tree-Sitter parses all source files, extracting exported symbols, import edges, and a compact per-file summary into a SQLite database (.codepulse/index.db). Git history is scanned to record how often each file changes.
Update: On each update, only files changed since the last indexed git commit are re-parsed — a 50k-line repo updates in milliseconds. With install-hooks, this runs automatically after every commit.
Context: Given a token budget, a layered generator fills it from most to least important: repo overview → directory map → symbol table → import graph. Files are ranked by task relevance, then change frequency (most-edited files first), so the most useful content always fits within the budget.
Smart budget: --auto scales the token budget to your repo's actual complexity — tiny repos are skipped entirely, saving 100% overhead.
The index is stored per-repo (not globally) so each project has its own isolated snapshot.
Packages
Package Description
@aicodepulse/core Indexer engine (Tree-Sitter, SQLite, context generator)
@aicodepulse/cli codepulse CLI
@aicodepulse/mcp codepulse-mcp MCP server
License
MIT
About
Token-efficient codebase indexer for AI coding tools. Persistent, git-diff-aware index injected at session start — so Claude Code, Codex, and Cursor stop wasting tokens exploring your repo.
Resources
Readme
Uh oh!
There was an error while loading. Please reload this page.
Activity
Stars
1 star
Watchers
0 watching
Forks
0 forks
Report repository
Releases
No releases published
Packages 0
Uh oh!
There was an error while loading. Please reload this page.
Contributors
Uh oh!
There was an error while loading. Please reload this page.
Languages
TypeScript 99.8%
JavaScript 0.2%