CodeRadar v0.5.4

Live semantic graph of your codebase — incremental, queryable, LLM-writable.

CodeRadar maintains an incrementally updatable graph of your code's logical structure, enabling LLMs and developer tools to both query and safely rewrite code through a unified pipeline. Based on techniques from CodeGraph (MIT License).

Why CodeRadar

CodeGraph pioneered the semantic code graph for agents — CodeRadar builds on that foundation with capabilities CodeGraph doesn't have:

The key insight: CodeGraph answers "what is this codebase?" — CodeRadar answers that and "what was it yesterday?" and "what would it look like if I changed X?" and "apply that change safely."

Performance

Head-to-head benchmarks (N=5 median, lower is better):

CodeRadar wins on small-to-medium Python/Rust projects due to zero runtime boot overhead. On large TypeScript codebases, CodeGraph's hand-written per-language Rust walkers and flat-buffer emission are still faster than the generic .scm-query engine, but the gap narrowed from 2.77× to 1.75×. See performance-roadmap.md for the optimization backlog.

Architecture

Python Layer (CLI, Visualizers, Framework Resolvers, GraphRAG, MCP Server)
        │
    PyO3 FFI  +  register_synthetic_edge() bridge
        │
Rust Core (ProjectedGraph, Tree-sitter 18-lang, Parallel Extraction,
           Resolution Cascade L1-L3, Query Engine, Mutation Engine)
        │
    Macrame DB (bitemporal persistence with valid_from/valid_to timestamps)

Quick Start

pip install coderadar-rs

# Initial analysis (includes framework detection)
coderadar init src/

# Query
coderadar query "functions where is_async == true"

# Explore call flows
coderadar explore UserService.create --direction downstream

# Watch for changes
coderadar watch src/ --debounce 50

# Visualize
coderadar visualize module_graph --format graphviz src/

Python API

import coderadar

# Initial analysis
graph = coderadar.analyze("src/")

# Query
for cls in graph.query("classes where inherits_from contains 'BaseModel'"):
    print(cls.name, [m.name for m in cls.methods])

# Framework-aware exploration (Django/Flask/FastAPI/Go/Actix routes included)
flow = graph.explore(["UserService.create"], direction="downstream")

# Callers (includes framework edges: route → handler)
callers = graph.callers_of("views.py::user_detail")

# Update after file change
report = graph.update_file("src/core/engine.py")

# Mutation (LLM-driven)
plan = graph.plan_body_replacement(
    entity_id="src/auth.py::validate_user",
    new_body="    return bool(re.match(r'^[^@]+@[^@]+$', email))",
    dry_run=True
)

# Module children resolution
children = graph.module_children("src/auth.py::auth")
for cls in children["classes"]:
    print(cls["name"], cls["grammar_kind"])

# Temporal queries (Macrame bitemporal)
past = graph.as_of("2026-08-01T00:00:00Z")

Language Support

Resolution Cascade

Stack Graphs (L1 in v3.3 spec) was deferred to post-v1. CodeGraph ships 30+ languages at production scale with zero Stack Graphs dependency — compiler-grade scope disambiguation is not required for MCP agent use cases.

Framework Resolvers

CodeRadar detects and extracts framework-specific patterns that tree-sitter can't see:

Framework edges are registered in the Rust graph — agents can trace from URL patterns to handler functions via callers_of() / callees_of().

v0.5.4 Feature Highlights

• Single-pass cursor-driven extraction — QueryCursor directly drives entity emission, eliminating the two-pass tag→walk pipeline. Inline fn-ref subtree scanning during function emission. 37% faster on real-world TypeScript codebases.
• Parallel extraction pipeline — 3-phase design: collect → parallel parse/tag/walk (fragment merge) → sequential projection commit.
• 18-language query files — per-language .scm queries with automated compile validation. C/C++ and TypeScript/JavaScript query files split to eliminate grammar mismatches.
• Query compilation caching — CompiledQuery wraps pre-compiled queries + pre-indexed capture tags; compiles once per language, not per file.
• grammar_kind field — raw tree-sitter node kind on every Class entity (e.g. class_declaration/struct for Swift)
• Function-as-value capture — detects self.on_click = handler, callback assignments, return values, kwargs
• Cross-file fn-ref — resolves imported names across module boundaries
• Noise filtering — builtin type filter (70+ types), literal receiver filter, name stoplist (12 names)
• Docstring extraction — preceding comment runs for all languages, not just @docstring captures
• Elixir def/defp — precise extraction via predicate queries
• __all__ detection — =, +=, .extend(), .append() patterns
• module.children() — resolves child entity IDs to full dicts
• Parameter annotations — type annotations extracted and filtered for builtins
• Live file watcher — notify-based debounced watcher with incremental re-indexing
• Graphviz visualizer — call graph rendering with SCC cycle highlighting
• Scoped call resolution — per-file resolution with caller/callee tracking
• Benchmark pipeline — balanced (50 modules × 1000 calls) and heavy (100 modules × 4000 calls) correctness tests

Project Structure

core_indexer/              # Rust core
  queries/                 # 18 .scm query files (one per language)
  src/
    extract/               # Tree-sitter: tagger (query cursor) + walker (hierarchy) + docstring + decorators
    update/                # Incremental diff + patch + WAL
    resolve/               # Resolution cascade (import_graph, orchestrator, signature, cache, stack_graph stub)
    query/                 # Pest grammar + execution engine
    mutation/              # AST-aware refactoring (rope, indent, WriteGuard)
    fs/                    # File watcher (notify) + git integration
    graph.rs               # In-memory ProjectedGraph + parallel extraction + reverse indexes
    storage.rs             # Macrame concept/edge persistence
    lib.rs                 # PyO3 FFI bindings

py_agent/src/coderadar/    # Python layer
    resolvers/             # Django, Flask, FastAPI, Go, Actix framework resolvers + __all__ exports
    embedding/             # Content-addressed dedup
    agent/                 # GraphRAG query pipeline
    lsp/                   # Persistent LSP warm pool
    mutation/              # Tool router for LLM
    mcp/                   # MCP server (explore, node, search, affected)
    query/                 # Query planner + templates + cache
    visualizers/           # Mermaid + Graphviz (SCC cycle highlighting)

docs/                      # Specifications + code review + performance roadmap
tests/                     # 140 Python tests (E2E, MCP, framework resolvers, benchmarks)

Configuration

# .coderadar.toml
[project]
languages = ["python"]
roots = ["src/", "tests/"]

[resolution]
min_confidence = 0.3

[macrame]
db_path = ".coderadar/store/coderadar.db"

[mutation]
enabled = true
default_dry_run = true

[performance]
worker_threads = 4
debounce_ms = 50

License

MIT — incorporates techniques from CodeGraph (MIT License).