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 · 简体中文

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:

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.

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

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.

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

Evolving. A fix made once carries forward, so the trace gets better the more it runs.

You do not throw anything away. Flowtrace runs the skills and the agent you already use. A skill you have becomes a trace, a long chat that worked becomes a trace, a finished session you do not want to rebuild becomes a trace. From then on it is something you can follow, steer, and run again.

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.

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:

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.