Skip to content
Back to search

Flowtrace

Run a task with AI as a flow of steps you keep, reuse, and refine, not a one-off chat.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aiscientists-dev--flowtrace/badge.svg)](/listings/aiscientists-dev--flowtrace)

HTML

<a href="/listings/aiscientists-dev--flowtrace"><img src="/api/listings/aiscientists-dev--flowtrace/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 198 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="docs/assets/hero.png" width="440" alt="Flowtrace">
  3. # Flowtrace
  4. **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.**
  5. Works with the agent you already use: Claude Code, Codex, Cursor.
  6. [![GitHub stars](https://img.shields.io/github/stars/AIScientists-Dev/flowtrace?style=flat-square&logo=github)](https://github.com/AIScientists-Dev/flowtrace/stargazers) [![MIT License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE) [![Homepage](https://img.shields.io/badge/Homepage-morphmind.ai-lightgrey?style=flat-square)](https://morphmind.ai) [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/x9mtbMEx) [![X](https://img.shields.io/badge/X-Follow-000000?style=flat-square&logo=x&logoColor=white)](https://x.com/morphmind__ai?s=11)
  7. [**What it does**](#what-it-does) · [**Get started**](#get-started) · [**Examples**](#examples) · [**Docs**](docs/trace/README.md)
  8. **English** · [简体中文](docs/README.zh-CN.md)
  9. ⭐ **If Flowtrace looks useful, star it** *(button's top-right)* — it's how we decide what to keep building in the open.
  10. </div>
  11. ---
  12. 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.
  13. 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:
  14. - It is too much to follow. The thread grows longer than you can hold, and you lose track of what was decided and why.
  15. - You cannot check it. A confident wrong answer looks exactly like a right one.
  16. - You cannot steer it. One bad assumption in the middle means redoing the whole thing and hoping the good parts survive.
  17. - It does not last. Every session is a cold start, and the good ones evaporate into scrollback.
  18. 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:
  19. <div align="center">
  20. <table><tr>
  21. <td align="center" valign="top"><a href="docs/assets/examples/nvda-decision.png"><img src="docs/assets/cap/hero-flow.png" height="280" alt="A trace shown as a clean flow: frame the thesis, research four angles in parallel, fold them into a valuation, deliver a one-page brief"></a><br><sub>The flow · click to enlarge</sub></td>
  22. <td align="center" valign="top"><a href="docs/assets/examples/nvda-decision.pdf"><img src="docs/assets/cap/hero-deliverable.png" height="280" alt="The deliverable, a fixed-format research-note PDF: cover, rating and summary, embedded charts, and numbered references"></a><br><sub>The deliverable · click to open</sub></td>
  23. </tr></table>
  24. </div>
  25. <p align="center"><a href="docs/assets/examples/nvda-decision.pdf"><strong>Read the full research-note PDF</strong></a></p>
  26. ## What it does
  27. Same skills, same agent. Running that work as a trace is what changes:
  28. **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.
  29. <div align="center">
  30. <img src="docs/assets/transparent.gif" width="520" alt="A trace running: it moves through its steps one at a time, each leaving a file on disk">
  31. <br><sub>Each step runs in turn and writes its output to a file.</sub>
  32. </div>
  33. **Grounded.** Every result points back to the files it came from, so you verify instead of trust.
  34. <div align="center">
  35. <table><tr>
  36. <td align="center" valign="top"><a href="docs/assets/cap/grounded-finance.png"><img src="docs/assets/cap/grounded-finance.png" height="300" alt="A finance result card titled trend, momentum and risk line up: four research charts (price, RSI, MACD, drawdown), a passing trend-and-momentum check, and the files they came from"></a><br><sub>Finance</sub></td>
  37. <td align="center" valign="top"><a href="docs/assets/cap/grounded-clinical.png"><img src="docs/assets/cap/grounded-clinical.png" height="300" alt="A clinical result card: survival benefit HR 0.62, a Kaplan-Meier curve and passing checks, citing km_curve.png"></a><br><sub>Clinical</sub></td>
  38. </tr></table>
  39. <sub>Two high-stakes decisions, same shape: the finding, its charts, the checks that pass, and the files they came from.</sub>
  40. </div>
  41. **Steerable.** Fix one step and only what depends on it re-runs. The rest stays put.
  42. **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.
  43. <div align="center">
  44. <img src="docs/assets/cap/traceable.png" width="720" alt="Three steps over the same run: pick any step in the node map, open its full version history, then travel back to an older commit to see its state then, v2 gradient-boost AUC 0.84 versus v1 logistic 0.78">
  45. <br><sub>Pick any step, open its history, travel to any past commit.</sub>
  46. </div>
  47. **Reusable.** A finished task becomes a trace you run again on new input. The method is reused, not rebuilt.
  48. **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.
  49. **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.
  50. 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.
  51. <div align="center">
  52. <table>
  53. <tr>
  54. <td align="center" valign="top"><a href="docs/assets/onramp/convert.png"><img src="docs/assets/onramp/convert.png" width="400" alt="Convert a skill into a trace: its written steps become a flow of real, checkable steps"></a></td>
  55. <td align="center" valign="top"><a href="docs/assets/onramp/distill.png"><img src="docs/assets/onramp/distill.png" width="400" alt="Distill a long session into a trace: the reasoning kept as steps, the back-and-forth dropped"></a></td>
  56. </tr>
  57. <tr>
  58. <td align="center" valign="top"><a href="docs/assets/onramp/plan.png"><img src="docs/assets/onramp/plan.png" width="400" alt="Turn a plan into a trace: the same plan, now something you can steer and run"></a></td>
  59. <td align="center" valign="top"><a href="docs/assets/onramp/handoff.png"><img src="docs/assets/onramp/handoff.png" width="400" alt="Keep a successful run as a trace, not a chat log: re-open the whole job, every step's files and checks, and run it again"></a></td>
  60. </tr>
  61. </table>
  62. </div>
  63. 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.
  64. ## Get started
  65. The fast path is to hand the repo to an agent. Point a coding agent (Claude Code, Codex, Cursor) at this folder and say:
  66. > _"Install Flowtrace and run the tailored-resume example."_
  67. 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.
  68. Two ways to get a trace:
  69. - **Try a reference.** Each example ships as a builder that creates a real trace folder and walks one full run.
  70. ```bash
  71. bash scripts/examples/tailored-resume/build.sh # → ~/traces/tailored-resume/
  72. flowtrace serve # → http://localhost:3000
  73. ```
  74. - **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`.
  75. A run is steerable: stop at any step, change it, and the steps that depend on it re-run while the rest stay put.
  76. <details>
  77. <summary>Install by hand</summary>
  78. ```bash
  79. git clone https://github.com/AIScientists-Dev/flowtrace.git
  80. cd flowtrace
  81. ./scripts/install.sh # builds + symlinks flowtrace to ~/.local/bin/
  82. ```
  83. Update with `git pull && ./scripts/install.sh`. Override the symlink target with `INSTALL_DIR=…`. Building from source or contributing? See [CONTRIBUTING.md](./CONTRIBUTING.md).
  84. </details>
  85. ## Examples
  86. **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](docs/EXAMPLES.md):
  87. <div align="center">
  88. <table><tr>
  89. <td align="center" valign="top"><a href="docs/EXAMPLES.md#saas-dd"><img src="docs/assets/examples/feat-saas-dd.png" height="240" alt="SaaS acquisition due diligence flow"></a><br><sub><a href="docs/EXAMPLES.md#saas-dd">SaaS due diligence</a></sub></td>
  90. <td align="center" valign="top"><a href="docs/EXAMPLES.md#security-cicd"><img src="docs/assets/examples/feat-security-cicd.png" height="240" alt="security CI/CD pipeline flow"></a><br><sub><a href="docs/EXAMPLES.md#security-cicd">Security CI/CD gate</a></sub></td>
  91. <td align="center" valign="top"><a href="docs/EXAMPLES.md#distill-mind"><img src="docs/assets/examples/feat-distill-mind.png" height="240" alt="distill a mind into a skill flow"></a><br><sub><a href="docs/EXAMPLES.md#distill-mind">Distill a mind into a skill</a></sub></td>
  92. </tr></table>
  93. </div>
  94. Plus six more:
  95. - Career: [Tailored Résumé Generator](docs/EXAMPLES.md#tailored-resume)
  96. - Investing: [Comprehensive Stock Analysis](docs/EXAMPLES.md#nvda-decision)
  97. - Research / writing: [Industry Deep-Dive Report](docs/EXAMPLES.md#research-writer)
  98. - Software engineering: [Bug-Fix Learning Loop](docs/EXAMPLES.md#swe-bugfix)
  99. - Growth / marketing: [Weekly Paid-Ads Optimization](docs/EXAMPLES.md#paid-ads)
  100. - Design / decks: [Talk → Magazine Slide Deck](docs/EXAMPLES.md#talk-to-deck)
  101. ## Documentation
  102. A trace is one git repository. `trace.json` declares the steps, their dependencies, and the final deliverable. Each run lives under `runs/<run_id>/`:
  103. ```
  104. <trace_root>/
  105. ├─ .git/ standard git repo, the audit trail
  106. ├─ trace.json the static plan (steps + deliverable)
  107. ├─ scripts/ shared code used by 2+ steps
  108. ├─ resources/ shared static material (refs, papers, master data)
  109. ├─ steps/<step_id>/
  110. │ ├─ STEP.md per-step contract + impl hints
  111. │ ├─ scripts/ step-local code
  112. │ └─ resources/ step-local material (figures, PDFs, fixtures)
  113. └─ runs/<run_id>/
  114. ├─ state.json run status (sole source of truth)
  115. ├─ replies/NNNN.json append-only structured-output stream
  116. └─ <step_id>/ run-time files (assets + scratch)
  117. ```
  118. 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.
  119. 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.
  120. Steps pass data through files, not parameters: each step writes its output, and a downstream step reads it.
  121. | To learn | Read |
  122. |---|---|
  123. | The idea, in depth | [PHILOSOPHY.md](docs/trace/PHILOSOPHY.md) |
  124. | Driving a trace as an agent | [docs/trace/CLI.md](docs/trace/CLI.md) |
  125. | Making a trace | [skills/make-trace/SKILL.md](skills/make-trace/SKILL.md), or run `/make-trace` |
  126. | The format spec | [SCHEMA.md](docs/trace/SCHEMA.md) and [FIELDS.md](docs/trace/FIELDS.md) |
  127. | All examples | [docs/EXAMPLES.md](docs/EXAMPLES.md) |
  128. ---
  129. ## Community
  130. **If Flowtrace is useful to you, consider starring the repo. It helps others find it.**
  131. - **Contributing**: see [CONTRIBUTING.md](./CONTRIBUTING.md), and look for [good first issues](https://github.com/AIScientists-Dev/Flowtrace/labels/good%20first%20issue).
  132. - **GitHub Issues**: [report bugs / propose changes](https://github.com/AIScientists-Dev/flowtrace/issues)
  133. - **Discord**: [discord.gg/x9mtbMEx](https://discord.gg/x9mtbMEx)
  134. - **X**: [@morphmind__ai](https://x.com/morphmind__ai?s=11)
  135. ---
  136. MIT. See [`LICENSE`](./LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.