Flowtrace re-runs only the dependents of a step you change, and keeps the run in git

Four named ways a chat-shaped run fails

The problem statement is specific about failure modes rather than vague about productivity, and it names four.

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, which is the argument for grounding rather than for a better model.

You cannot steer it. One bad assumption in the middle means redoing the whole thing and hoping the good parts survive.

And it does not last. Every session is a cold start, and the good ones evaporate into scrollback.

The setup is that 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 when it finishes you are left with a wall of messages.

Crucially, the documentation concedes that this is fine for a quick question. The line between the two cases is drawn by stakes and repetition, not by effort. A quick one off is just chat. What justifies a trace is a result you would have to verify, or a task you are going to run again.

Those four failures map one to one onto the four properties the tool claims, which is a sign the design was derived from the problem rather than assembled from features.

Steerable means only the dependents of a changed step re-run

This is the claim that separates a trace from a saved transcript, and it is stated twice in the documentation.

The steerable property: fix one step and only what depends on it re-runs, the rest stays put. And in the getting started section, the same thing again as an operational instruction: a run is steerable, stop at any step, change it, and the steps that depend on it re-run while the rest stay put.

For that to be true the steps cannot be a transcript. They have to form a graph with declared edges, and the earlier property about structured reading says exactly that: the work is exposed as a graph of files rather than a linear transcript, with the agent loading a step's contract, inputs, and outputs only while working on it and following explicit dependencies. The stated purpose is to bound working context and reduce drift.

So the dependency structure is authored rather than inferred, and that has a consequence worth naming. If a step does not declare the steps it feeds, then changing it will not cause those to re-run, and you get stale downstream output. Nothing in the documentation claims automatic edge discovery.

Traceability rides on the same substrate. The whole run is files and git, so it does not vanish when you close the tab. You can stop and resume, hand it to a teammate, or read the full history, and the interface offers to travel to any past commit.

A step that misses its bar gets replaced by the version that passes

Two properties describe what happens to a trace after it has been run once, and they are the least mechanical part of the design.

Reusability is the simpler half. A finished task becomes a trace you run again on new input, and the phrasing is deliberate: the method is reused, not rebuilt. That is the difference between saving a transcript of an execution and saving the procedure that produced it.

Evolving is the more interesting half. 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.

Three properties are doing work there. There is a bar, which means the evaluation is stated rather than felt. There is a next version, which means a failing step is a normal event and not a reason to start over. And the passing version sticks, which means selection happens by outcome rather than by intention.

The grounding property is what makes that survivable. Every result points back to the files it came from, so you verify instead of trust. In the two high stakes examples shown, a finance decision and a clinical one, the shape is the same: the finding, its charts, the checks that pass, and the files they came from. That is what a bar can be measured against, and it is also why the evolution loop does not quietly drift toward something that merely sounds better.

Read together, the three properties form a closed loop: files you can check, procedures you can rerun, and versions that get selected by passing.

The onramp accepts anything that already exists

The argument for adoption is that you do not have to change how you work to get a trace.

The claim is that 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.

Four entry points are illustrated for that, named as convert, distill, plan, and handoff. The convert case is the obvious one, taking something already written and giving it a step structure. The distill case is taking a long session and keeping only the decisions. The plan case is interesting because it means the value is available before execution, not only as a record afterwards. The handoff case is the one that connects to the traceability claim, since it is about transferring a run to someone else.

The mechanism for the third path is a skill rather than code. The `make-trace` skill turns any source, named explicitly as a `SKILL.md`, a runbook, a chat log, or a finished task, into a trace. You copy the `skills/make-trace/` directory into the agent's skills directory and run `/make-trace`.

So there are two ways to end up with a trace. You run one of the bundled examples, which ships as a builder that creates a real trace folder and walks one full run, or you convert something you already have.

And the framing is honest about the limits: not every task needs this.

Install is a script that symlinks into your local bin

The install path is a shell script and a symlink, and there is no package manager entry.

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

The script builds the CLI and links it into the local bin directory. Updates are a pull followed by running the same script again, so the upgrade path and the install path are one command pair. The symlink target can be overridden with an `INSTALL_DIR` environment variable for anyone who keeps binaries elsewhere.

Running a trace takes one more command:

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

The builder writes a real trace folder under the home directory, and `serve` starts the web view on port 3000 where the flow lights up step by step. So the loop is build, serve, watch.

The fast path skips all of it. The documentation suggests pointing a coding agent at the folder and asking it to install the tool and run the tailored resume example, on the reasoning that the agent already knows how to run a build script.

Traces themselves land in the home directory rather than inside the repository, which is what makes a trace portable enough to hand to a teammate.

The web view is embedded in the Rust binary, not served separately

The repository metadata calls this a TypeScript project, and the CLI is a Rust workspace. Both are true, and the manifest explains what the Rust side does.

The workspace globs every crate under `crates/` and pins one version across them, at 0.1.0, edition 2021, MIT. The dependency list reads as a description of the architecture rather than a grab bag.

Serving is `axum` with the macros feature, plus `tower` and `tower-http` configured for filesystem serving, tracing, and CORS. So the same process answers the API and hands out the interface.

The interface itself is compiled in. `rust-embed` with mime guessing and include-exclude packs assets into the binary at build time, and `mime_guess` picks the content types. That is why there is no separate asset server to run and no bundler step in the install script.

File watching is first class, with `notify` and a debouncer. That is the mechanism behind the live stepping in the web view, since a step writing its output file is a filesystem event.

Two other dependencies point at specific features. `similar` is a diff library, which is what a history view and travelling to a past commit are built on. `zip` with deflate only produces the export artifacts. And `clap_complete` means the CLI ships shell completions.

The release profile is tuned for a shipped binary: thin link time optimisation, a single codegen unit, and symbols stripped.

Nine examples, two documentation languages, no releases

The example gallery is the largest part of the project, and the repository state is worth reading alongside it.

There are nine examples, built from popular open source skills and spanning different domains, each openable for its flow and for a one command demo. The ones named in the gallery are SaaS due diligence, a security CI/CD gate, and a distillation example, alongside the tailored resume used in the quick start. What the set has in common is the stakes profile from the problem statement: decisions with consequences rather than tasks with steps.

Documentation is bilingual, with an English root and a Simplified Chinese version under `docs/`, plus a separate trace documentation index. The repository root is short: `crates/`, a `frontend/` directory, `scripts/`, `skills/`, `docs/`, and the manifests. The `frontend/` directory is where the interface source lives, which is the answer to the TypeScript metadata.

Then there is the version situation. The workspace version is 0.1.0 and the repository has no GitHub releases at all. The last push to main is dated 2026-06-09, roughly four months before this snapshot, and the repository has 485 stars, 35 forks, and 4 open issues.

The star count is also load bearing in a specific way: the README says outright that starring is how the maintainers decide what to keep building in the open. So the roadmap signal is public and popularity driven, which is worth weighing when you are deciding whether a 0.1.0 tool will still be there in a year.

Editorial conclusion

Flowtrace fits the tasks the documentation itself names, a buy or sell call, a due diligence memo, a security gate, and anything you will verify or run twice, and it is the wrong tool for a quick question, where the project says plainly that you should just chat. Three things to know before you commit. The re-run scoping is the whole value, so a step with no declared dependency will not cause the things that logically depend on it to re-run, and the dependency edges are what you are authoring. The install path is a script that builds and symlinks into your local bin directory rather than a package manager entry, so there is no upgrade path outside git pull. And the version is 0.1.0 with no tagged releases, the last commit to main is dated 2026-06-09, and the repository is marked as a TypeScript project while its CLI is a Rust workspace, which tells you to read the source rather than trust the language badge.

Frequently asked questions

Official sources

1. AIScientists-Dev/Flowtrace on GitHub
2. Issues
3. License: MIT
4. Project website
5. README