| suggest_next | 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)
|
| index_repo | 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.
|
| embed_repo | 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
|
| overview | 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. 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}.
|
| prepare_context | 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.
Phase 5.31 bench: +16.0% F1 (p=0.012*, n=93). 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).
|
| focus | 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"
|
| hotspots | 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 response
|
| blast_radius | 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 response
|
| diff_context | 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.
|
| dead_code | 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)
|
| lookup | 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 response
|
| symbols | 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 response
|
| file_map | 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 response
|
| dependencies | 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 response
|
| architecture | 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 response
|
| stats | 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 response
|
| report_feedback | 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
|
| learn_recommendation | 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
|
| get_patterns | 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
|
| run_kit | 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
|
| search_semantic | 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)
|
| watch_repo | 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")
|
| unwatch_repo | Stop watching a repository for file changes. repo_path: absolute path to the repository root
|
| cochange_context | 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"
|
