TempoGraph is an MCP server that builds a deep dependency graph of your codebase to provide AI agents with precise, context-aware file and symbol information for coding tasks.
Core Task Assistance
prepare_context – One-shot context for a coding task; selects relevant files, symbols, and hotspots within a token budget (proven +18.6% file prediction improvement)
diff_context – Impact analysis for changed files, with git auto-detection (unstaged, staged, commit, branch)
cochange_context – Uses git history to find files that frequently change together (logical coupling detection)
Codebase Understanding
overview – Project type, languages, biggest/most complex files, module dependencies, and circular import warnings
file_map – File tree with top symbols per file
architecture – High-level module-to-module dependency view
symbols – Full symbol index: every function, class, component, hook, and type with signatures and relationships
stats – File/symbol/edge/line counts and estimated token costs per mode
Dependency & Impact Analysis
focus – Task-scoped context around a query or symbol, including callers/callees and related files
blast_radius – What breaks if you change a given file or symbol (importers, callers, cross-language bridges)
dependencies – Detects circular imports and shows dependency layer structure
lookup – Natural language questions: "where is X defined?", "what calls X?", "what imports X?"
Risk & Quality
hotspots – Ranks riskiest symbols by coupling, complexity, and cross-file callers
dead_code – Exported symbols never referenced elsewhere — cleanup candidates
get_patterns – Coding conventions, naming patterns, and structural idioms
Search
search_semantic – Hybrid FTS5 keyword + vector similarity search to find symbols by meaning (requires embed_repo)
embed_repo – Generate local vector embeddings (BAAI/bge-small-en-v1.5) for semantic search
Automation & Workflows
run_kit – Composable multi-tool workflows (e.g., explore, deep_dive, change_prep, code_review, health)
suggest_next – Predicts the most useful next tool based on learned session patterns
learn_recommendation – Data-driven context strategy recommendations based on task type and usage history
Repository Management
index_repo – Build or rebuild the semantic graph index
watch_repo / unwatch_repo – Live incremental graph updates on file changes
Feedback
report_feedback – Log whether a tool's output was helpful to improve future recommendations
Supports deep extraction for Python, TypeScript, JavaScript, Rust, Go, Java, C#, and Ruby, plus generic support for 170+ additional languages. Warm queries run in ~21ms with content-hashed storage so only changed files are re-parsed.
Your AI agent finds the right files. Every time.
TempoGraph builds a dependency graph of your codebase and gives your AI coding agent exactly the files it needs before making changes. One tool call. No guessing.
AI coding agents guess which files to look at. They search by filename, grep for keywords, and hope for the best. In large codebases, they miss critical dependencies, break things downstream, and waste tokens reading irrelevant code.
Related MCP server: better-code-review-graph
pip install tempographAdd to your MCP config (Claude Code, Cursor, Windsurf, or any MCP client):
{
"mcpServers": {
"tempograph": {
"command": "tempograph-server",
"args": []
}
}
}Your agent calls prepare_context with a task description. TempoGraph returns the exact files that matter — based on real dependency analysis, not text matching.
Tested on real PRs from django, flask, httpx, fastapi, requests, and pydantic. Task: predict which files need to change.
Model | Without TempoGraph | With TempoGraph | Improvement |
GPT-4o | 21.7% F1 | 27.5% F1 | +27% |
GPT-4o-mini | 19.2% F1 | 24.5% F1 | +28% |
qwen2.5-coder:32b | — | — | +18.6% (p=0.049) |
Consistent improvement across every model. 2-3x more tasks helped than hurt. No other code context tool publishes retrieval benchmarks with statistical significance.
your repo ──→ tree-sitter parse ──→ symbols + edges ──→ SQLite graph
│
AI agent calls prepare_context ─────────┘
│
◄── KEY FILES + callers + callees + risk signalsParses your code with tree-sitter into a structural dependency graph
Content-hashed and stored in SQLite — only changed files get re-parsed
Warm queries in ~21ms. Branch switching doesn't trigger a rebuild
Knows when NOT to inject context (adaptive gating avoids harming diffuse commits)
Beyond prepare_context, TempoGraph exposes 24 MCP tools for deeper analysis when your agent needs it:
Tool | When to use it |
| "What breaks if I change this file?" |
| "Show me everything related to auth" |
| "Which files are riskiest to change?" |
| "What can I safely delete?" |
| "What's the impact of my current changes?" |
| "Orient me in this new codebase" |
Tool | What it does |
| One-shot context for a task — the primary tool |
| Repository orientation: size, languages, entry points |
| Connected subgraph around a symbol — callers, callees |
| What breaks if you change this file or symbol |
| Impact analysis of changed files |
| Ranked risk list — complexity x coupling x size |
| Unreferenced symbols — cleanup candidates |
| "Where is X?", "What calls X?" |
| Circular imports, dependency layers |
| Module-level dependency view |
| Full symbol inventory |
| File tree with top symbols per file |
| Hybrid keyword + vector + structural search |
| Files that historically change together |
| Predicts the next useful tool call |
| Composable multi-tool workflows |
| Token budget estimates |
| Codebase conventions and idioms |
| Log whether output was useful |
| Suggestions from feedback history |
| Build or rebuild the graph |
| Live incremental updates |
| Generate vector embeddings |
# Orient in a new repo
tempograph ./my-project --mode overview
# What's connected to auth?
tempograph ./my-project --mode focus --query "authentication"
# What breaks if I touch db.ts?
tempograph ./my-project --mode blast --file src/lib/db.ts
# Find dead code to clean up
tempograph ./my-project --mode deadfrom tempograph import build_graph
graph = build_graph("./my-project")
results = graph.search_symbols("handleLogin")
importers = graph.importers_of("src/lib/db.ts")
dead = graph.find_dead_code()Python, TypeScript, JavaScript, Rust, Go, Java, C#, and Ruby get deep extraction (custom tree-sitter handlers). 170+ additional languages are supported via generic handler. pip install tempograph[full] for everything.
If TempoGraph saves you time, consider sponsoring the project. Sponsors get early access to new features.
TempoGraph is AGPL-3.0 — free to use, modify, and distribute. If you use TempoGraph in a network service (SaaS, hosted IDE, AI coding platform), AGPL requires you to open-source your service code. If that doesn't work for you, commercial licenses are available.
Contact eali@needspec.com for commercial licensing terms.
AGPL-3.0 — free to use. Network service use requires source disclosure, or a commercial license.
High-level architecture view: modules, their roles, and inter-module dependencies. Groups files into top-level directories, shows import and call edges between modules. Use for understanding how the codebase is organized at a macro level.
exclude_dirs: comma-separated directory prefixes to skip
output_format: "text" (default) or "json" for structured responseInputs: repo_path, exclude_dirs, output_format. Returns: result
What breaks if you change this file or symbol? Shows importers, external callers, component render chains, and cross-language bridges.
Parameter priority: if BOTH file_path and query are provided, query wins.
- file_path: whole-file blast radius, e.g. "src/lib/db.ts"
- query: symbol-level blast radius (more precise), e.g. "Sparkline.max"
For large monolith files, prefer query over file_path.
At least one of file_path or query must be provided.
output_format: "text" (default) or "json" for structured responseInputs: repo_path, file_path, query, exclude_dirs, +1 more. Returns: result
Files that historically co-change with a given file (logical coupling).
Uses git history to find files frequently changed in the same commits.
Useful for discovering hidden dependencies: if A and B co-change 80% of
the time, a change to A likely requires reviewing B.
file_path: path relative to repo root (e.g., "tempograph/render.py")
n_commits: how many recent commits to analyze (default 200)
output_format: "text" (default) or "json"
Inputs: repo_path, file_path, n_commits, output_format. Returns: result
Find exported symbols never referenced by other files. Potential cleanup targets — unused exports, orphaned functions, dead interfaces. Respects Python all for precise export tracking.
max_tokens: cap output size (default 8000) to prevent context overflow
exclude_dirs: comma-separated directory prefixes to skip
output_format: "text" (default) or "json" for structured response
include_low: include low-confidence (likely false positive) symbols (default False,
saves ~47% tokens — ~1,300 tokens on a typical repo)Inputs: repo_path, max_tokens, exclude_dirs, output_format, +1 more. Returns: result
Dependency analysis: circular imports and layer structure. Shows import cycles and which files depend on which layers. Use before refactoring to understand the dependency graph.
exclude_dirs: comma-separated directory prefixes to skip
output_format: "text" (default) or "json" for structured responseInputs: repo_path, exclude_dirs, output_format. Returns: result
Impact analysis for changed files. Pass comma-separated paths OR use scope to auto-detect from git.
changed_files: comma-separated file paths (overrides scope if provided)
scope: git detection mode — "unstaged" (default), "staged", "commit", "branch"
max_tokens: cap output length (default 6000)
output_format: "text" (default) or "json" for structured response
NOTE: When using scope (git auto-detect), the repo must be a git repository.
Returns a NOT_GIT_REPO error if it isn't. If changed_files is provided,
git is not required.
Inputs: repo_path, changed_files, scope, max_tokens, +2 more. Returns: result
Generate embeddings for semantic search across all symbols in the codebase.
Run after index_repo to enable hybrid search (FTS5 + vector similarity).
Uses BAAI/bge-small-en-v1.5 (33MB, runs locally on CPU, no API keys).
Only embeds symbols without existing vectors — fast on subsequent runs.
Requires: pip install tempograph[semantic]
repo_path: absolute path to repository
Inputs: repo_path, exclude_dirs, output_format. Returns: result
File tree with top symbols per file. Good for orientation and understanding project structure. Shows directory groupings, file sizes, and key symbols.
Use overview for a cheaper orientation, or focus for task-specific context.
max_symbols_per_file: how many symbols to show per file (default 8)
max_tokens: cap output (default 4000; 0 = use default)
exclude_dirs: comma-separated directory prefixes to skip
output_format: "text" (default) or "json" for structured responseInputs: repo_path, max_symbols_per_file, max_tokens, exclude_dirs, +1 more. Returns: result
Get task-scoped context. Describe what you're working on and get back the relevant symbols, their callers/callees, complexity warnings, and related files — all within a token budget.
query: natural language description or symbol name
max_tokens: cap output length (default 4000)
exclude_dirs: comma-separated directory prefixes to skip
output_format: "text" (default) or "json" for structured response
Examples: "authentication middleware", "Canvas command palette",
"database migrations", "AI assistant toolbar"
Inputs: repo_path, query, max_tokens, exclude_dirs, +1 more. Returns: result
Get coding patterns and conventions for this codebase.
Returns a catalog of naming conventions, structural patterns, module roles,
and repeated idioms. Use this before writing new code to ensure you follow
the project's existing conventions.
query: optional filter (e.g. "render", "plugin", "test", "handler")
max_tokens: cap output size (default 4000)
exclude_dirs: comma-separated directory prefixes to skip
output_format: "text" (default) or "json"
Examples:
- get_patterns(".") → full convention catalog
- get_patterns(".", query="plugin") → plugin-related patterns
- get_patterns(".", query="render") → rendering conventions
Inputs: repo_path, query, max_tokens, exclude_dirs, +1 more. Returns: result
Find the riskiest symbols: highest coupling, complexity, and cross-file callers. These are where bugs cluster and changes are most dangerous. Use before modifying unfamiliar code to know what to be careful around.
top_n: how many hotspots to return (default 15)
exclude_dirs: comma-separated directory prefixes to skip
output_format: "text" (default) or "json" for structured responseInputs: repo_path, top_n, exclude_dirs, output_format. Returns: result
Build the semantic index and return a full orientation. Run this once at session start. Returns project type, stats, top files, complexity hotspots, and module dependency map. ~500-700 tokens — everything an agent needs to begin.
exclude_dirs: comma-separated directory prefixes to skip (e.g. "archive,vendor,dist").
Also reads from .tempo/config.json "exclude_dirs" array. Both sources are merged.
output_format: "text" (default) or "json" for structured response with
{status, data, tokens, duration_ms} fields.Inputs: repo_path, exclude_dirs, output_format. Returns: result
Get a data-driven context strategy recommendation from learned usage patterns.
Returns the best modes to use, expected token cost, and success rate for a given task type.
Known task types: debug, feature, refactor, code_navigation, orientation, cleanup,
architecture, dependency_audit, code_review, task_preparation, output_review,
learning, patterns.
Leave task_type empty to see all learned strategies for this repo.
NOTE: Requires the tempo package to be installed. Returns a LEARN_UNAVAILABLE
error if not installed — install with: pip install -e .
output_format: "text" (default) or "json" for structured response
Inputs: repo_path, task_type, output_format. Returns: result
Answer a specific question about the codebase. Understands patterns like: - "where is X defined?" - "what calls X?" / "who uses X?" - "what does X call?" / "dependencies of X" - "what files import X?" - "what renders X?" (JSX/component tree) - "what implements X?" / "what extends X?"
Falls back to fuzzy symbol search if no pattern matches.
Typically ~100-500 tokens.
question: natural language question about the codebase
output_format: "text" (default) or "json" for structured responseInputs: repo_path, question, exclude_dirs, output_format. Returns: result
Repo orientation: project type, languages, biggest/most complex files, module dependencies, circular import warnings. ~500 tokens. Use this to understand the codebase structure. For coding tasks, call prepare_context(task="...") next — it selects the right context automatically.
repo_path: path to the repository (try "/demo" for a FastAPI demo)
exclude_dirs: comma-separated directory prefixes to skip (e.g. "archive,vendor")
output_format: "text" (default) or "json" for structured {status, data, tokens, duration_ms}.Inputs: repo_path, exclude_dirs, output_format. Returns: result
The recommended tool for coding tasks. Give it your task and get back a token-budgeted context with the right files, symbols, and hotspots — all in one call. Proven +18.6% file prediction improvement (p=0.049*, n=45). 95% helpful rate. Use this instead of calling index_repo → focus → blast_radius manually.
task: describe what you're working on. Two modes are auto-selected:
- PR/commit titles ("Merge pull request #123 from org/fix-auth-bug",
"fix: prevent null pointer in handler", "Fix teardown callbacks (#5928)")
→ keyword extraction from branch name → per-keyword symbol focus → KEY FILES list
→ proven +7% file prediction improvement on real PRs (canonical n=159, p=0.035*)
- General coding tasks ("add pagination to user list", "refactor database layer")
→ fuzzy symbol search → overview fallback if no match
task_type: optional hint — "changelocal" forces keyword-extraction path regardless
of task format; also accepts "debug", "feature", "refactor", "review"
max_tokens: total token budget for the response (default 6000)
exclude_dirs: comma-separated directory prefixes to skip
baseline_predicted_files: optional list of files already predicted by the model
(for adaptive injection). Two skip conditions:
1. If len(baseline) ≥ 3 → returns "" (model is highly confident with 3+ predictions;
any context disagrees more than it helps). Evidence: falcon bl=1.000, 3 correct preds
→ av2 without this guard injected anyway → F1 1.0→0.5 (commit 988960b/d4eb3c8).
2. If overlap(baseline ∩ KEY FILES) ≥ 50% → returns "" (model already knows the files).
Otherwise: returns full context (model needs the structural graph bridge).
Bench (canonical): python3 -m bench.changelocal.analyze --canonical --conditions baseline,tempograph_adaptive
Canonical result (n=159 Python+JS): +6.9% F1 (p=0.035*). Cost: 2× inference for ~37% of tasks.
precision_filter: if True, skip context when >4 key files are found (topic too broad).
Canonical bench: python3 -m bench.changelocal.analyze --canonical --conditions baseline,tempograph_precision
Canonical result (n=159 Python+JS): +3.7% F1 (p=0.21, ns). Default False (plain tempograph = +6.0%
outperforms precision_filter on canonical corpus). Enable only for high-baseline repos.
definition_first: if True, when a keyword produces too-broad focus (>10 files) and no path match,
fall back to the *defining file* of the top-ranked symbol (requires score≥10 and ≤2 defining files).
Handles "redirect" → flask/helpers.py instead of injecting nothing.
Default True (enabled).
output_format: "text" (default) or "json" for structured response
Returns: overview summary + focused context + KEY FILES + hotspot warnings,
all within the token budget. JSON format adds `key_files` (parsed list) and `injected` (bool).
Inputs: repo_path, task, task_type, max_tokens, +5 more. Returns: result
Report whether tempograph output was helpful for your current task. Call after using any tempograph tool. Helps improve the product.
mode: which tool you used (index_repo, overview, focus, hotspots, blast_radius, diff_context, dead_code, lookup, symbols, file_map, dependencies, architecture, stats, prepare_context, learn_recommendation)
helpful: true if the output helped, false if not
note: optional — what was missing or what worked well
Inputs: repo_path, mode, helpful, note. Returns: result
Run a composable kit — a named multi-mode workflow that combines tempograph modes into a single token-budgeted response.
kit: name of the kit to run, or "list" to show all available kits.
Built-in kits:
explore — overview + hotspots (orient to a new codebase)
deep_dive — focus + blast (deep-dive into a symbol)
change_prep — diff + focus (prepare for a code change)
code_review — dead + hotspots + focus (code review workflow)
health — hotspots + dead (codebase health check)
Custom kits can be defined in .tempo/kits.json.
query: optional symbol or topic for focus/blast steps
max_tokens: total token budget across all kit steps (default 4000)
exclude_dirs: comma-separated directory prefixes to skip
output_format: "text" (default) or "json"
Examples:
- run_kit(".", "explore") → overview + hotspots
- run_kit(".", "deep_dive", query="render_focused") → focus + blast on symbol
- run_kit(".", "health") → hotspots + dead code
- run_kit(".", "list") → show all available kits
Inputs: repo_path, kit, query, max_tokens, +2 more. Returns: result
Hybrid semantic + structural search across all symbols in a codebase.
Combines FTS5 keyword matching with vector similarity (if embeddings exist)
using Reciprocal Rank Fusion. Finds symbols by meaning, not just exact name match.
Example: search_semantic(repo, "handle user authentication") finds auth-related
functions even if they're named validate_token or check_credentials.
Run `python3 -m tempograph <repo> --embed` first to enable semantic vectors.
repo_path: absolute path to repository
query: natural language description of what you're looking for
limit: max results (default 10)
Inputs: repo_path, query, limit, exclude_dirs, +1 more. Returns: result
Quick repo statistics: file count, symbol count, edge count, line count, and estimated token costs for each mode. Use to plan your token budget.
exclude_dirs: comma-separated directory prefixes to skip
output_format: "text" (default) or "json" for structured responseInputs: repo_path, exclude_dirs, output_format. Returns: result
Suggest the most useful next tool based on learned session patterns.
Analyzes historical usage events to predict what tool agents typically call next.
When prev_tool is provided, uses second-order Markov (prev→current→next) which is
significantly more accurate than first-order on repeated workflows.
Example: suggest_next(current_tool='focus', prev_tool='overview') returns
'hotspots (100%)' instead of the less certain 'hotspots (58%)' from first-order.
repo_path: absolute path to repository
current_tool: the tool you just called (e.g. 'focus', 'overview')
prev_tool: the tool called before current_tool (optional; enables second-order prediction)
Inputs: repo_path (required), current_tool, prev_tool, output_format. Returns: result
Full symbol index — every function, class, component, hook, type in the repo with signatures, locations, and relationships.
WARNING: Can be very large. Default max_tokens=8000 prevents context window overflow.
For scoped queries, use focus or lookup instead — they're much cheaper.
max_tokens: cap output (default 8000; 0 = use default)
exclude_dirs: comma-separated directory prefixes to skip
output_format: "text" (default) or "json" for structured responseInputs: repo_path, max_tokens, exclude_dirs, output_format. Returns: result
Stop watching a repository for file changes.
repo_path: absolute path to the repository root
Inputs: repo_path (required). Returns: result
Start watching a repository for file changes. Incrementally updates the graph DB when files are added, modified, or deleted. Uses Rust-backed file watcher for performance.
repo_path: absolute path to the repository root
exclude_dirs: comma-separated directories to ignore (e.g. "node_modules,dist")
Inputs: repo_path, exclude_dirs. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 24 tools
Each tool has a clearly distinct purpose with detailed descriptions. Even related tools like overview, focus, and prepare_context target different scopes (high-level, task-specific, recommended for coding). Potential overlaps are minimal and well-explained.
Tool names follow a lowercase_underscore pattern but mix verb_noun (index_repo, watch_repo) with noun phrases (architecture, hotspots, dead_code). Inconsistent but still readable and meaningful.
24 tools is on the higher end but appropriate given the breadth of analysis features (orientation, risk, dependencies, search, etc.). Each tool addresses a specific need without feeling redundant.
The tool set covers most aspects of codebase analysis: orientation, search, risk, dependencies, patterns, change impact, and workflow recommendations. Missing only rare edge cases, but core workflows are well-supported.
Shared context for your codebase: a hosted code knowledge graph over MCP. Free plan, OAuth sign-up.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
