Flowdex

Dynamic agent defined programmatic workflows, manual context compaction, silent verification commands, smarter explorer context gathering, and automatic AST-Grep linting rule extraction.

Comment

Inspiration

My inspiration for Flowdex started shortly after the GPT-5.6 release, after spending some time building with 5.6, I noticed my usage drain was higher than I anticipated. I decided to export my session logs and measure where all my tokens were going, to do this I used GPT-5.6 Pro and had it create a data analysis report. I was surprised to find that 36.6 of all of my usage was going towards orchestration overhead, and not implementation. The bulk was 10 second waits, agent-status checks, agent completion polling, small verification turns, and large cache reads.

This made me question the current agentic engineering paradigms: Why should I be running the most powerful AI model available, just to run and orchestrate operations that should be programmatic?

Waiting on worker completion, running small verification commands, playing telephone between worker and reviewer agents, deciding what subagents can run in parallel, these are all things that don't need a several trillion parameter model to decide.

After some research, I found some existing "workflow" systems, but they all still routed each transition through model turns, or allowed hundreds of agents to spawn recursively. I wanted workflows that took the model out of the loop where possible, and reduced token cost, rather than burning through tokens and adding abstractions around model involvement.

I also wanted to preserve the Codex desktop UX, Flowdex was therefore built into the Codex app rather than as a Standalone Harness TUI, Skill, or MCP/Plugin. Workflows, task status, and progress summaries still continue appear natively through the existing Codex app without modifying the front end.

What it does

Flowdex adds an event driven workflow runtime into Codex. A planning model writes a workflow in JavaScript, saves it globally or inside a local repository, and starts it with a native tool. The workflow then coordinates agents, verification, review, context collection, and boundaries. All while parent model sleeps, consuming 0 tokens.

Programmable Workflows

Workflows can define:

  • Runs representing one long-horizon complete objective.
  • Ordered phases with inherited instructions, verification commands, and agent profiles.
  • Tasks with dependencies, model configuration, verication, review, and advised file scopes.
  • Parallel task running for independent tasks.
  • Dynamic task insertion into running phases.
  • Human or orchestrator approval boundaries.
  • Nested reusable workflows with strict JSON inputs and outputs.
  • Named signals and event driven model suspension.
  • Global workflows for reusable behavior and repository workflows for project specific automation. Workflows execute in Codex's native V8 runtime, so they don't require Node.js. The workflow API is intentionally built from composable primitives, rather than hard coded "worker" and "reviewer" roles. The same messaging and resume operations can support an implementation loop, two researchers exchanging discoveries, or any other agent protocol.

A simplied workflow looks like this:

const run = await flowdex.startRun({
  name: "update-parser",
  agents: {
    explorer: { profile: "explorer" },
    implementer: { profile: "default" },
    reviewer: { model: "gpt-5.6-luna", reasoningEffort: "high" },
  },
  phases: [{
    name: "implementation",
    instructions: "Preserve the existing wire format.",
    tasks: [{
      name: "update-reader",
      agent: "implementer",
      instructions: "Implement and commit the parser update.",
      verification: ["cargo test -p parser"],
      review: {
        agent: "reviewer",
        instructions: "Check layout compatibility.",
        maxRounds: 2,
      },
    }],
  }],
});

await run.wait();

Event driven orchestration

Flowdex waits on runtime events, rather than repeatedly waking the model and causing cache read from a model turn.

A suspended workflow can resume when:

  • A child agent finishes.
  • A verification command completes.
  • A named signal is emitted.
  • A workflow reaches an approval boundary.
  • The user sends a steering input.
  • The workflow completes or fails. User steering will still wake the parent, queue messages remain queued.

Flowdex also produces automatic progress summaries like "Running parser update" or "Reviewing update-reader". These reuse the Codex App's existing reasoning summary display, but are not added to the conversation history, workflow output, or next model request.

Isolated tasks

Each scheduled task receives its own own Git worktree. Agents are instructed to commit their changes with a short summary, and Flowdex records the relationship between:

  • Workflow run
  • Task
  • Agent thread
  • Agent operation
  • Source commit
  • Integrated commit
  • Model configuration

Completed task commits get integrated into the workflows repository checkout. Advisory read/write scopes help the scheduler avoid running conflicting tasks in parallel, without turning those scopes into forced access controls that might need to be expanded by the orchestrator.

We use SQLite to store the workflow definitions, task state, commit attributions, reviews, context metadata, boundaries, and signals.

Silent verification and repair

Tasks and phases can declare verification commands like git diff --check, verification commands that pass don't wake the model and consume a turn, nor do they inject output into the model context. Failed verification commands can be routed back to its associated agent with the failure output. Verification repair limits can be declared, which limit the max number of verification rounds before escalation. Verification limits and review limits are tracked separately.

Direct agent messaging and context re-use

Workflow agents can send messages without routing every response through a game of telephone via the orchestrator. JavaScript loops provide explicit round budgets, making the messaging mechanism useful beyond just worker-reviewer pairs.

Agents also have context-reuse, with 3 options for the reuse straegy:

  • Keep the existing context thread and history
  • Compact the existing thread before continuing
  • Ask for a structured handoff and start a fresh subagent thread

Context packs

Context packs let explorer agents send important source material and summaries directly to tasks that require it, without loading into the planner or orchestrators context window. However if either the planner, orchestrator, or any other agent would like to read the recorded context, it can inspected with the context read tool:

read_flowdex_context({ pack }) -> {
  pack,
  status: "fresh" | "missing" | "stale",
  fragments: [{
    key,
    version,
    path,
    lineStart,
    lineEnd,
    summary?,
    content,
  }],
}

Explorers get their own recording tool to record context fragments, each fragment records:

  • A pack and stable key
  • Repository relative file
  • Start/End lines
  • Optional summary
  • Source hash and version
publish_flowdex_context({
  pack
  key,
  path,
  line_start,
  line_end,
  summary?
})

Publishing a newer fragment under the same key supersedes the older version. Before a dependent task starts, Flowdex programmatically reads the current ranges from the file handles and inserts the fresh context into that tasks instructions.

If a pack is missing or stale, Flowdex will automatically dispatch an explorer agent to refresh it. Unrelated ready tasks can continue while the collection happens.

Attributable review and automatic repair routing

Review agents are given a dedicated reporting tool for precise findings:

report_flowdex_review({
  findings: [{
    file: "src/parser.rs",
    lineStart: 42,
    lineEnd: 48,
    reason: "Field offsets no longer match the encoded header.",
    ruleKey: "parser-field-order",
    astGrepSuitable: true,
  }],
});

Flowdex maps each findings through Git history and commit records to locate the responsible task operation and agent. The finding can then return directly to that agent for repair.

If a line cannot be attributed to an agent, Flowdex broadens the lookup to the entire file. If no owner can be idenfied still, it suspends at an orchestrator or human boundary instead of guessing.

Review rounds, repaired commits, verification results, and exact resolutions remain linked in SQLite.

Review history that becomes linting knowledge

Repeated reviewer findings can become AST-grep rule candidates.

Flowdex scans resolved findings for stable rule keys that exceed a configurable repetition threshold. It returns deterministic examples with their source and integrated commits, while excluding rules already created in the repository. Promotion to lint rules is not autonomous, a user reviews each candidate rule before the final rule writing agent creates an AST-grep YAML rule. Approved rules can then run explicitly or automatically after command verification.

This stops common reviewer issues from costing manual model review, instead transforming it into an automated silent verification command.

Deliberate context compaction

Flowdex adds a native compact_context tool that schedules Codex's existing compaction that the model can call.

A configurable context window token threshold can also inject a one time developer reminder asking the model to compact at the next natural task boundary. This lets models shake un-needed context between tasks and reduces overall token consumption.

Codex app integration

Flowdex uses the existing app-server events for:

  • Child-agent lifecycle items
  • Reasoning-summary progress reporting
  • Steering
  • Workflow tools
  • Approval boundaries The workflow runtime remains invisible to the model history when appropriate, but not invisible to the user.

Flowdex also supports selecting Codex's existing multi-agent V1 or V2 backend through the flowdex.toml configuration file. Multi agent version will force all models to run on the selected version, allowing modern 5.6 models to still use older Codex models as subagents. This was primarily added due to a Codex bug preventing gpt-5.6-luna agents from being spawned by Sol or Terra parent threads, but also helps with user configurability incase they have a specific preference.

Installation

The packaged installer supports both Windows and macOS through the commands:

flowdex install
flowdex uninstall
  • Windows users will need to use .\flowdex install/uninstall

On windows it configures the Codex App's backend Codex CLI path through the user environment. On macOS it updates the appropraite shell profile for zsh, bash, or fish. Installation includes the Flowdex configuration and default workflow assets, while uninstall can optionalyl remove Flowdex-created data through the --purge flag.

How we built it

Flowdex is implemented as a modified Codex CLI and app-server backend, rather than an external controller, MCP server, or harness.

The implementation has two main layers:

  • codex-flowdex, a repository independent Rust crate that owns workflow validation, SQLite state, Git worktrees, context fragments, review attribution, AST-grep execution, and workflow loading.
  • Narrow bridges inside Codex Core that connect the runtime to existing agents, shell execution, code mode, compaction, app server events, configuration, and cancellation. Saved workflows run as native V8 modules. Their APIs are implemented as hidden workflow-only tools, so low level orchestration capabilities are available to JavaScript without becoming a collection of model-callable tools.

I reused existing Codex infrastructure whenever possible to make Flowdex feel like a natural extension of Codex:

  • AgentControl for child sessions
  • Existing model and agent-profile resolution
  • ShellRuntime and ToolOrchestrator for commands
  • Native compaction paths
  • Existing app-server lifecycle events
  • InputQueue for steering
  • Code-mode cells as workflow run identifiers
  • Git worktrees for task isolation The work scheduler is specifically data-oriented. Definitions are validated once, persisted into run, phase, task, dependency, and agent records, and then advanced through explicit state transitions. Ready tasks are selected from dependency and scope data rather than repeated orchestrator model decisions.

Challenges we ran into

The biggest challenge I faced when working on Flowdex was trying to make workflows behave like a native part of Codex, while ensuring that the parent model sleeps and saves tokens.

When building Event-Driven suspension, 5.6 found several races that polling normally masks. Steering was able to arrive while a named signal was being consumed, a queue-only mailbox update could replace a pending wake notification, a second wait could begin before a remote observer had fully retired. Reused agents also needed operation specific completion IDs so that two overlapping resumes couldn't consume each others results. The agents fixed this by treating wait source and submitted operation as owned state instead of being the "latest status".

Keeping the Codex App was also its own problem, I wanted workflow activity to be user visible but not injected into the model context. The first complete runs with Flowdex showed that the agents were working, but they were invisible to the desktop UI because Flowdex initially spawned them below the normal collaboration tool path. We added app-server lifecycle events for every workflow child and automatic reasoning summary progression updates to show progress to the user.

Model selection also presented another issue, the multi agent protocol prevented Sol parent agents from spawning Luna workers because of conflicting multi agent versions. While this was more of a Codex bug patch rather than a novel "Flowdex feature", I had the agents add a separate multi_agent_version setting that allows users to force all models to use the chosen V1 or V2 backend for all models. This allows for Sol parent threads to now spawn gpt-5.3-codex-spark workers, when previously it would treutn an error before.

Git worktrees were one of the biggest headaches, a task could finish, commit, verify, and integrate successfully, but then the entire workflow would fail when trying to cleanup because Windows still held a short lived file handle. Git had already unregistered the worktree, but deleting the directory returned "access denied", causing the integrated work to be treated as a failed task. The final fix separated semantic cleanup from actual physical cleanup. Once the validated worktree is unregistered, the workflow can complete while a bounded background cleanup retries the same path.

Accomplishments that we're proud of

I'm proud of the fact that all the Flowdex features were initially novel ideas that I came up with when facing issues while using Codex myself. I believe I had a unique perspective on Codex usage, being a 5x Pro user I use Codex heavily while still needing to keep track and ration my usage. This drove me to come up with ideas to solve real issues that I faced, rather than try and build something just to enter build week.

When I ran the final acceptance workflow test, it was able to successfully demonstrate the entire system as a complete pipeline. It launched Luna and Sol agents, exchanged messages, collected and injected a context pack, ran dependency ready tasks in paralle, detected an intentional AST-grep violation, sent a line attributed review finding back to the responsible agent, integrated the repair, queued a task dynamically, verified the final state, and returned a structured result. The parent wait woke once for an explicit test signal and once for terminal completion.

I'm also proud that Flowdex intentionally builds features as composable primitives rather than hard coded roles. The bundled reviewer-worker workflow is made from the same primitives that drive a two-researcher exchange loop, a conditional nested workflow, or a custom agent protocol.

Context packs are one of my favorite implementations, I came up with the idea randomly while brainstorming Flowdex features using the new Live ChatGPT Voice mode. Context packs let explorers collect information that can either be actual source code, or prose summaries, without ever passing through planner or orchestrator models, but also without restricting them from accessing it if they need to.

What we learned

I actually learned a lot about using the new gpt-5.6 models in agentic programming, one of the funniest but most frustrating lessons I learned was how much gpt-5.6 likes to overengineer things when given the freedom. I even had to start over from scratch after running 5.6 unsupervised for 24 hours, because it started to complicate things when left to its own devices. This lesson helped direct me towards a smarter way to use Codex, instead of creating a several thousand one shot spec and handing it to an implementation worker, I instead just naiively explained all the features I wanted to add to gpt-5.6-sol in planning mode, and used speech-to-text to transcribe my ramblings. I had it just create a simple feature list without delving into the raw implementation details, I read over the plan and confirmed it was what I wanted. From there I had the planning agent write incremental implementation plans for specific sections/features, and had it create new Codex tasks/threads. I had never used Codex like this before, but it is surely going to be my default from now on.

I also learned a lot more about the internals of Codex from this, random details about Code Mode default timeouts, polling, tool schemas and behavior. I'm sure that these new insights will help me to be that much more efficient when using Codex (Or now I'll be using Flowdex)

What's next for Flowdex

I definitely will continue to iterate on Flowdex, some things I'd like to look into adding are:

  • Process-restart recovery, letting interrupted workflows continue even after app/system restarts
  • More built in workflows, currently we just have worker-reviewer and researcher workflows, but I'd like to make workflow creation faster and more efficient by adding full cookie cutter runs that can be used.
  • Token consumption forecasting, this project initially started as a way to reduce token usage, but I also would like to be able to let users know how much usage is expected to be consumed by a given run.

I've also been considering moving away from the Codex app, since I am unable to modify the UI easily. Some features I'd like to add but cant within Codex are things like dedicated workflow visualization inside of the harness app, letting users see the flow of phases and tasks, results, and other details. Another one of the hottest debates for people using AI Agents for programming is: "Should you spend time reading the code". I believe that as developers we should be reading the model output, because ultimately you own what you publish. However to make this easier I want to add a better way to review agent generated code, my ideal setup is:

  • Panel that shows code with substantial margins on either side.
  • Code is highlighted with color coded identifiers to label whether code has not been reviewed, is agent reviewed, or human reviewed.
  • Highlighted code chunks represent a commit from a worker, where the commit and agent summary of the changes is displayed on the margin, along with the agent who made it.
  • Feedback can be sent to the original worker agent to fix or change the code as needed, and finally can be marked as human reviewed when the code meets the users standards.

I'm not sure which path I'll take, but I'm excited to take ownership of my own user experience.

Built With

Share this project:

Updates