Flowtrace transforms AI agent outputs from ephemeral text streams into persistent, verifiable, and reusable "traces." It addresses the challenge of managing complex AI-driven tasks by structuring their execution as a series of discrete, file-based steps. This approach benefits users of agents like Claude Code, Codex, and Cursor by providing transparency, enabling rigorous verification, and facilitating iterative refinement of AI-generated work, making it suitable for high-stakes decisions and repeatable processes.

How It Works

Flowtrace re-imagines AI agent execution as a traceable flow rather than a linear chat. Core to its design is the concept of a "trace," a structured record of an agent's work stored as a Git repository. Each task is broken down into discrete steps, with every step's output saved to disk as files. This file-centric approach allows downstream steps to consume outputs directly, enabling precise reruns of only affected components when changes are made ("steerability"). The use of Git provides a robust audit trail, making the entire process transparent, verifiable ("grounded"), and persistent across sessions.

Quick Start & Requirements

Installation involves cloning the repository and running a setup script:

git clone https://github.com/AIScientists-Dev/flowtrace.git
cd flowtrace
./scripts/install.sh

This installs the flowtrace CLI tool, typically symlinked to ~/.local/bin/. Updates are handled via git pull && ./scripts/install.sh. A quick start involves running provided examples, such as the tailored resume generator:

bash scripts/examples/tailored-resume/build.sh
flowtrace serve

This command builds a trace in ~/traces/tailored-resume/ and launches a local web view at http://localhost:3000 to visualize the execution flow. The project is designed to be handed to coding agents (Claude Code, Codex, Cursor) for automated setup and execution. No specific Python version or hardware prerequisites (like GPUs) are detailed in the README.

Highlighted Details

• Transparency & Groundedness: Work is exposed as a navigable flow of steps with file outputs, allowing verification against source data, moving beyond trust to demonstrable evidence.
• Steerability & Reusability: Modifying a single step triggers reruns only for dependent steps, preserving unchanged work. Completed traces can be directly reused for new inputs.
• Traceability & Persistence: The entire run is managed within a Git repository, ensuring history is preserved, tasks can be resumed, and work can be shared seamlessly.
• Structured Reading: Agents interact with traces by loading specific step contracts, inputs, and outputs on demand, bounding context and reducing drift.
• Diverse Examples: Nine examples demonstrate Flowtrace's application across domains including SaaS due diligence, security gates, investment analysis, and software development.

Maintenance & Community

The project encourages community engagement through GitHub starring for prioritization and contributions via CONTRIBUTING.md and "good first issues." Community channels include a Discord server (discord.gg/x9mtbMEx) and an X (formerly Twitter) presence (@morphmind__ai).

Licensing & Compatibility

Flowtrace is released under the MIT License, which is permissive and generally allows for commercial use and integration into closed-source projects without significant copyleft restrictions.

Limitations & Caveats

Flowtrace is positioned for tasks where verification or repeatability is crucial; it may be overkill for simple, one-off chat interactions. The README does not detail specific unsupported platforms, known bugs, or the project's current development stage (e.g., alpha/beta).