codepulse

Your agents finally see what the code does when it runs.

Live behavioral models joined with static structure — queried as compact answers over MCP, not megabytes of traces.

agent ↔ codepulse

› structural_search("async def $NAME($$$):")
← 12 matches · api.py:40, …

› get_hot_paths(metric="invocations")
← PricingWorkflow.execute   148 221
← api.handle_checkout        90 014

› get_actual_callers("…execute")
← 6 callers · top: handle_checkout

› enable_targeted_instrumentation(30s)
← probe window active · budget held

Source text is not enough

Coding agents reason from files and symbols. Real systems also have hot paths, observed callers, failure concentration, and dead complexity. codepulse turns that runtime truth — and structural pattern questions over the AST — into something agents can ask for over one MCP surface.

What agents can ask

Compact summaries shaped for model context — never a firehose of call events.

Hottest functions Rank symbols by invocations, p95 duration, or exceptions in a session.
Actual callers & callees See who called a method in practice, not only what the AST declares.
Static vs observed Compare syntactic edges to runtime edges; find never-hit callees.
Adaptive deepen Time-boxed exact instrumentation on a small target set when baseline is thin.
Structural pattern search Ask ast-grep-style questions over the workspace via the tree-sitter indexer — no separate tool.
Uncovered complexity Surface symbols that look hard in the AST but never ran.
Bounded overhead Cheap always-on sampling by default; the controller owns the probe budget.

Structural search questions

Ask shape questions over the workspace with structural_search, then join matches to live hot paths and callers.

Find all async function definitions
async def $NAME($$$ARGS): $$$BODY
Where do we call requests.get?
requests.get($$$ARGS)
Show bare except: clauses
except: $$$BODY
Find every open(...) call site
open($$$ARGS)
Locate methods named execute
def execute($$$ARGS): $$$BODY
Find await of a named call
await $FUNC($$$ARGS)
Find raise HTTPException(...)
raise HTTPException($$$ARGS)
Find decorator + function pairs
@$DECORATOR def $NAME($$$ARGS): $$$BODY

How it works

One local daemon. Runtime agents as plugins. MCP for the AI host.

01
Baseline ingest
The Python agent aggregates coarse call stats and posts batches to the Rust daemon. SQLite stores the live behavioral model.
02
Static index + patterns
tree-sitter walks the project, extracts symbols and complexity, joins them to runtime identity by SymbolId, and answers on-demand structural_search patterns — no ast-grep CLI.
03
MCP answers
Cursor, Claude Code, and other hosts call tools like structural_search, get_hot_paths, and get_function_runtime_summary — compact answers only.
04
Probe windows
When evidence is thin, the agent enables targeted instrumentation for a bounded window. On expiry or budget breach, exact mode auto-disables.

MCP tool surface

TypeScript server talking to the local daemon. Designed for agent workflows.

structural_search: AST pattern match over the workspace (metavariables, capped matches).
get_hot_paths: Ranked hotspots by invocations, duration, or exceptions.
get_function_runtime_summary: Invocations, exceptions, latency percentiles, top callers.
get_actual_callers / get_actual_callees: Observed edges with counts.
get_static_summary: Complexity, size, syntactic callee counts.
compare_static_vs_runtime: Declared vs observed structure in one answer.
enable_targeted_instrumentation: Deepen a small target set for a fixed duration under budget.
list_uncovered_hot_symbols: Complex static symbols with zero runtime hits.

Built for agents, not dashboards

Local-first. Privacy fail-closed. Platform language independent of the target runtime.

Answers over streams — summaries fit model context.
Adaptive cost — overhead is a controller-owned budget.
Static + dynamic together — catalog, pattern search, and live stats.
Local-first — works offline in your repo; no SaaS required.
Fail closed on privacy — no args, returns, or locals by default.
Runtime agents are plugins — Python and .NET today; protocol-ready for more.

Stack: Rust daemon · tree-sitter indexer (Python + C#) · TypeScript MCP · Python ≥3.12 agent · .NET Harmony agent

Give this to your agent

Paste the prompt into a new chat for the current project. Full tools and install script live on the Agents page.

Set up codepulse in this repo: clone detroitpro/codepulse, run the daemon on this workspace root, wire the MCP server, install the Python or .NET agent, then use get_hot_paths / structural_search.

You are setting up codepulse (https://github.com/detroitpro/codepulse) for THIS repository so I can ask runtime questions via MCP.

Do the following:

1. Detect the primary language (Python ≥3.12 preferred for first setup; .NET if this is a C# app).
2. If codepulse is not already available locally, clone https://github.com/detroitpro/codepulse.git to a sensible path (or use an existing clone). Build: `cargo build -p codepulse-daemon`.
3. Start the daemon against THIS workspace root:
   `./target/debug/codepulse --root <THIS_REPO_ROOT> --db <clone>/.codepulse/<name>.db --listen 127.0.0.1:7420`
   Verify: `curl -s http://127.0.0.1:7420/health`
4. Install MCP: in `packages/mcp`, `npm install && npm run build`. Add Cursor MCP config pointing at packages/mcp/dist/index.js with CODEPULSE_ENDPOINT=http://127.0.0.1:7420.
5. Install the matching runtime agent (Python: codepulse_agent.install(); .NET: CodePulseAgent.Install + CODEPULSE_INCLUDE).
6. Tell me how to exercise the app so events appear. Verify with get_hot_paths. Prefer answers over raw dumps.

Constraints: local-first; never request args/returns/locals. Skill: skills/codepulse/SKILL.md. Docs: docs/guide/GETTING_STARTED.md.

Give your agent a pulse on the running system

Open source. Point the MCP server at a workspace daemon, load the Python agent, and ask what actually runs.

Getting started View on GitHub