codeflow

Trace codebase call flows from an entry point and output structured graphs ready for AI agent ingestion.

Written in: Rust
Supports: Python · Rust · Dart source files
Outputs: flows.json (AI-optimized schema) · flows.mmd (Mermaid diagram)
AI interfaces: CLI · MCP server (Model Context Protocol)

---

Build

git clone <repo>
cd codeflow
cargo build --release
# Binary: ./target/release/codeflow

Install

curl -fsSL https://raw.githubusercontent.com/ImaCodingClown/codeflow/main/install.sh | zsh

---

CLI usage

Flat mode (simplest)

# Auto-detect language, trace from default entry point
codeflow src/main.rs
codeflow src/main.py

# Specify entry function and depth
codeflow src/main.py --fn main --depth 6

# Custom output prefix
codeflow src/server.rs --out reports/server_flows

analyze subcommand

codeflow analyze src/main.rs --fn main --depth 5 --out flows
codeflow analyze src/app.py --lang python --depth 4 --out app_flows
codeflow analyze src/lib.rs --json-only --quiet

--tree <fn_name> — function call tree

Show everything a function calls (downward) and everything that calls it (upward):

codeflow src/main.rs --tree process_records
codeflow src/app.py --tree DataStore.load --depth 4

# Example output:
# ╭─ process_records ─────────────────────────────────
#
#   ▼ callees (what this function calls)
# └── ○ process_records
#     ├── ○ validate_config
#     └── ○ DataStore::insert
#
#   ▲ callers (what calls this function)
# └── ○ process_records
#     └── ○ main
#
#   5 nodes  ·  6 edges in subgraph

The --tree flag also writes a focused <out>.tree.json and <out>.tree.mmd containing only the relevant subgraph.

MCP server mode

codeflow mcp
# Reads JSON-RPC 2.0 from stdin, writes responses to stdout
# stderr: progress/debug messages (safe to discard)

---

All flags

Flag	Default	Description
--lang	auto	python | rust | dart | auto
--fn	main	Entry function name
--depth	5	Max traversal depth
--out	flows	Output file prefix
--root	entry's parent	Project root for import resolution
--tree <fn>	—	Show tree for a function (prints to stdout)
--json-only	false	Skip Mermaid output
--mmd-only	false	Skip JSON output
--quiet	false	Suppress progress messages

---

Output formats

flows.json — AI agent schema

{
  "schema_version": "1.0",
  "meta": {
    "entry_point": "main::main",
    "language": "rust",
    "total_nodes": 12,
    "total_edges": 28,
    "entry_direct_calls": ["main::load_config", "main::connect", ...],
    "index_by_kind": {
      "function": ["main::main", "main::load_config", ...],
      "class": ["main::DataStore"],
      "extern": []
    }
  },
  "nodes": {
    "main::main": {
      "id": "main::main",
      "kind": "function",
      "name": "main",
      "module": "main",
      "file": "src/main.rs",
      "line": 58,
      "signature": "fn main()",
      "is_async": false,
      "is_public": false,
      "side_effects": ["io", "network", "raises"],
      "complexity": 4,
      "calls_external": false
    }
  },
  "edges": [
    { "src": "main::main", "dst": "main::load_config", "kind": "calls", "call_site_line": 59 }
  ],
  "ai_agent_hints": { ... }
}

Node kinds: function · async_function · method · class · module · extern
Edge kinds: calls · imports · contains · inherits · instantiates
Side effect tags: io · network · mutates_state · raises

flows.mmd — Mermaid flowchart

flowchart LR
    main__main["main [io,network,raises]"]
    main__load_config["load_config [io]"]
    ...
    main__main --> main__load_config

Paste into mermaid.live or any Mermaid-compatible renderer.

Visual conventions:

• [[ ]] nodes — external dependencies (⚡)
• [/ /] nodes — async functions (⟳)
• ( ) nodes — classes / structs
• Purple — entry point
• Orange — nodes with side effects
• Coral — external dependencies

---

MCP server

The codeflow mcp command runs a JSON-RPC 2.0 server over stdio following the Model Context Protocol spec.

Connecting from Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "codeflow": {
      "command": "/path/to/codeflow",
      "args": ["mcp"]
    }
  }
}

Connecting from any MCP client

{
  "command": "codeflow",
  "args": ["mcp"],
  "transport": "stdio"
}

Available MCP tools

analyze_file

Parse a source file and return its full call graph.

{
  "name": "analyze_file",
  "arguments": {
    "file": "/path/to/src/main.rs",
    "lang": "rust",
    "entry_fn": "main",
    "depth": 5,
    "format": "both"
  }
}

Returns: entry_point, language, total_nodes, total_edges, graph_json, graph_mermaid

get_tree

Get caller + callee tree for a specific function.

{
  "name": "get_tree",
  "arguments": {
    "file": "/path/to/src/main.rs",
    "fn_name": "process_records",
    "depth": 4
  }
}

Returns: focus, text_tree, callees, callers, subgraph_json, subgraph_mermaid

blast_radius

Get an N-hop blast radius around a function (both callers and callees), returned as a focused subgraph.

{
  "name": "blast_radius",
  "arguments": {
    "file": "/path/to/src/main.rs",
    "fn_name": "process_records",
    "radius": 2,
    "depth": 5
  }
}

Returns: focus, focus_id, radius, total_nodes, total_edges, subgraph_json, subgraph_mermaid

list_functions

List all functions/methods with signatures and side effects.

{ "name": "list_functions", "arguments": { "file": "/path/to/main.py" } }

get_node

Get full metadata + callers/callees for a specific node ID.

{
  "name": "get_node",
  "arguments": {
    "file": "/path/to/main.rs",
    "node_id": "main::DataStore::load"
  }
}

Recommended prompt for AI agents

You have access to the `codeflow` MCP tool for analyzing codebases.

When asked to understand how code works:
1. Use `analyze_file` on the entry point to get the full call graph
2. Use `get_tree` on specific functions to zoom in on their flow
3. Use `get_node` to get the signature and metadata of a specific function
4. Look for nodes with side_effects to identify I/O boundaries
5. Look for kind=extern nodes to identify external dependencies

The graph_json from analyze_file contains an `ai_agent_hints` field that
explains how to read the schema.

---

How parsing works

Python

Uses tree-sitter-python for full AST parsing. Resolves import and from ... import statements by walking the filesystem relative to --root. Extracts:

• Function/method signatures with type annotations
• Docstrings (first string expression in body)
• Class inheritance (inherits edges)
• Async/await detection
• Cyclomatic complexity (branch counting in AST)
• Side effects: file I/O, network calls, raise, global

Rust

Uses tree-sitter-rust for full AST parsing. Resolves mod foo; declarations to foo.rs or foo/mod.rs. Extracts:

• fn and async fn with pub/pub(crate) visibility
• impl blocks → methods qualified as TypeName::method_name
• struct, enum, trait definitions
• Cyclomatic complexity (branch counting in AST)
• Side effects: fs::, TcpStream, println!/eprintln!, panic!, unwrap(), unsafe

---

Project structure

src/
  main.rs           CLI entry point (clap), MCP dispatch
  graph.rs          Core data model: Node, Edge, FlowGraph
  output.rs         JSON and Mermaid serializers
  tree.rs           --tree: caller/callee subtree extraction
  mcp.rs            MCP JSON-RPC server over stdio
  parsers/
    mod.rs          Parser trait
    python.rs       Python parser (tree-sitter-python)
    rust_lang.rs    Rust parser (tree-sitter-rust)