Traceflow

See your local Node.js services talk to each other.

Traceflow discovers local listeners, attaches only when you ask it to, and turns related HTTP calls into an inspectable sequence diagram with request details and service logs.

Traceflow is designed for local development. It does not require a hosted collector or send telemetry.

Video

https://github.com/user-attachments/assets/6df8d237-a995-44cd-a413-fbab897a1d31

Requirements

• Node.js 22 or newer
• macOS or Linux
• lsof available on the host

Quick start

Run without installing:

npx traceflow-debugger

Or install the traceflow command globally:

npm install --global traceflow-debugger
traceflow

Run directly from a checkout:

npm install
npm start

Open http://127.0.0.1:9477, select Scan, and explicitly attach the local Node.js services you want to inspect. Traceflow never attaches to every open port automatically.

To try the bundled three-service example:

npm run demo

How it works

1. Traceflow scans loopback ports for local Node.js services.
2. You choose which processes to attach to or which configured services to start.
3. Traceflow groups related requests and renders the flow, timing, status, and logs.

Everything stays on your machine and captured data is held in memory only.

Features

• Sequence diagrams for related incoming and outgoing HTTP requests
• Browser-to-external fetch and XHR traces for attached local web apps
• Request and response headers and bodies with sensitive values redacted
• Pause, step, and resume controls for local requests
• Explicit attachment to already-running Node.js processes
• Reattach those services after they restart. Turn off Auto-reattach in Settings to stop that.
• Optional service startup from a local config file
• Listener discovery with repository badges
• Collapsed bursts for repeated requests without discarding raw traces
• Status, slow-hop, and pin filters, with failing and slowest hops marked on the diagram
• Pins that keep a trace when older ones expire
• Service logs linked to the request that wrote them
• Local service logs and a read-only MCP diagnostics server

Configuration

Configuration is optional. Without it, Traceflow starts with an empty service list and discovers local Node.js listeners through Scan.

To define services that Traceflow may start, copy the example into the project where you run Traceflow:

cp traceflow.config.example.json traceflow.config.json

Relative service working directories are resolved from the config file's directory. Use TRACEFLOW_CONFIG to select another file:

TRACEFLOW_CONFIG=./config/traceflow.json traceflow

traceflow.config.json is ignored by Git because commands and environment values are normally machine-specific. Attached services are remembered in traceflow.services.json, next to that config, and restored on the next start.

Security and privacy

Traceflow can inspect, instrument, start, and stop local processes. Only attach to processes you own or have permission to inspect.

• The server binds to loopback only.
• Mutating APIs and live streams require a random per-run token.
• Cross-origin and unexpected Host requests are rejected.
• Sensitive headers, query parameters, JSON fields, and common token formats are redacted before traces enter the in-memory store.
• Captured data is kept in memory and disappears when Traceflow exits.

Do not expose the Traceflow port through a proxy, tunnel, or public network. See SECURITY.md for vulnerability reporting.

Development

npm test
npm run demo

See CONTRIBUTING.md for contribution guidelines.

MCP diagnostics

traceflow-mcp exposes read-only tools for service health, compact trace summaries, and log search. It reads the local Traceflow instance at http://127.0.0.1:9477; set TRACEFLOW_URL to use another loopback port.

License

MIT