Flowtrace

Run your agent's work as steps you can follow, check, and reuse, instead of a stream of text that buries you and then disappears.

Works with the agent you already use: Claude Code, Codex, Cursor.

What it does · Get started · Examples · Docs

English · 简体中文

⭐ If Flowtrace looks useful, star it (button's top-right) — it's how we decide what to keep building in the open.

---

Real work with an agent happens as a stream of text. You run a skill and it does the whole task in one pass, or you go back and forth in a chat that keeps growing. Either way it piles up faster than you can follow, and once it is done you are left with a wall of messages.

For a quick question that is fine. For a buy or sell call, a due diligence memo, a security gate, anything you would actually need to verify or run again, it is a problem:

• It is too much to follow. The thread grows longer than you can hold, and you lose track of what was decided and why.
• You cannot check it. A confident wrong answer looks exactly like a right one.
• You cannot steer it. One bad assumption in the middle means redoing the whole thing and hoping the good parts survive.
• It does not last. Every session is a cold start, and the good ones evaporate into scrollback.

Flowtrace runs that same work as a trace: a flow of steps the agent moves through one at a time, each leaving its output on disk. Here is one, a buy or sell decision that ends in a fixed-format, citable PDF:

The flow · click to enlarge

The deliverable · click to open

Read the full research-note PDF

What it does

Same skills, same agent. Running that work as a trace is what changes:

Transparent. The work is a flow of steps you take in at a glance, not a thread you scroll. Each step's output is a file you open, so the intermediate work is right there instead of buried in messages.

_{Each step runs in turn and writes its output to a file.}

Grounded. Every result points back to the files it came from, so you verify instead of trust.

Finance

Clinical

_{Two high-stakes decisions, same shape: the finding, its charts, the checks that pass, and the files they came from.}

Steerable. Fix one step and only what depends on it re-runs. The rest stays put.

Traceable. The whole run is files and git, so it does not vanish when you close the tab. Stop and resume anytime, hand it to a teammate, read the full history.

_{Pick any step, open its history, travel to any past commit.}

Reusable. A finished task becomes a trace you run again on new input. The method is reused, not rebuilt.

Evolving. The trace gets better the more it runs. When a step misses its bar, the next version switches to a method that clears it, and the version that passes is the one that sticks.

Structured reading. A trace exposes the work as a graph of files, not a linear transcript. The agent reads it by structure and on demand, loading a step's contract, inputs, and outputs only while working on it and following explicit dependencies rather than carrying the whole history. This bounds working context, reduces drift, and yields a representation people and agents can both inspect and extend.

You do not start from scratch. A skill, a long session, a plan, a finished run: run any of them as a trace and you get the same steps you can follow, check, and run again. Open any one to read it full size.

Not every task needs this. A quick one off, just chat. Flowtrace earns its place when the result matters enough to verify, or when you will run the task again.

Get started

The fast path is to hand the repo to an agent. Point a coding agent (Claude Code, Codex, Cursor) at this folder and say:

"Install Flowtrace and run the tailored-resume example."

It installs the CLI, builds a real trace at ~/traces/tailored-resume/, and opens the web view at http://localhost:3000, where the flow lights up step by step.

Two ways to get a trace:

• Try a reference. Each example ships as a builder that creates a real trace folder and walks one full run.

  bash scripts/examples/tailored-resume/build.sh   # → ~/traces/tailored-resume/
  flowtrace serve                                  # → http://localhost:3000

• Make your own. The make-trace skill turns any source (a SKILL.md, a runbook, a chat log, a finished task) into a trace. Copy skills/make-trace/ into the agent's skills directory and run /make-trace.

A run is steerable: stop at any step, change it, and the steps that depend on it re-run while the rest stay put.

Install by hand

git clone https://github.com/AIScientists-Dev/flowtrace.git
cd flowtrace
./scripts/install.sh        # builds + symlinks flowtrace to ~/.local/bin/

Update with git pull && ./scripts/install.sh. Override the symlink target with INSTALL_DIR=…. Building from source or contributing? See CONTRIBUTING.md.

Examples

Nine examples built from popular open-source skills, spanning different domains. Open any one for its flow and a one-command demo in the examples gallery:

SaaS due diligence

Security CI/CD gate

Distill a mind into a skill

Plus six more:

• Career: Tailored Résumé Generator
• Investing: Comprehensive Stock Analysis
• Research / writing: Industry Deep-Dive Report
• Software engineering: Bug-Fix Learning Loop
• Growth / marketing: Weekly Paid-Ads Optimization
• Design / decks: Talk → Magazine Slide Deck

Documentation

A trace is one git repository. trace.json declares the steps, their dependencies, and the final deliverable. Each run lives under runs/<run_id>/:

<trace_root>/
├─ .git/                                    standard git repo, the audit trail
├─ trace.json                              the static plan (steps + deliverable)
├─ scripts/                                 shared code used by 2+ steps
├─ resources/                               shared static material (refs, papers, master data)
├─ steps/<step_id>/
│  ├─ STEP.md                               per-step contract + impl hints
│  ├─ scripts/                              step-local code
│  └─ resources/                            step-local material (figures, PDFs, fixtures)
└─ runs/<run_id>/
   ├─ state.json                            run status (sole source of truth)
   ├─ replies/NNNN.json                     append-only structured-output stream
   └─ <step_id>/                            run-time files (assets + scratch)

The same two-name convention (scripts/ for code that runs, resources/ for static material that doesn't) appears at both the trace root and inside each step. Anything reused across 2+ steps belongs at the trace root; single-step material stays inside the step folder. STEP.md references either with relative paths.

Every CLI write makes one git commit, scoped to exactly the paths it declares: state.json plus any --asset paths, or the new reply file plus its cited evidence paths. Scratch files stay untracked. The git history is the audit trail, and the UI can time-travel through it.

Steps pass data through files, not parameters: each step writes its output, and a downstream step reads it.

To learn	Read
The idea, in depth	PHILOSOPHY.md
Driving a trace as an agent	docs/trace/CLI.md
Making a trace	skills/make-trace/SKILL.md, or run /make-trace
The format spec	SCHEMA.md and FIELDS.md
All examples	docs/EXAMPLES.md

---

Community

If Flowtrace is useful to you, consider starring the repo. It helps others find it.

• Contributing: see CONTRIBUTING.md, and look for good first issues.
• GitHub Issues: report bugs / propose changes
• Discord: discord.gg/x9mtbMEx
• X: @morphmind__ai

---

MIT. See LICENSE.