MachineFlow

• 

  Multi-Codex Agents Collaboration

Inspiration

Modern coding agents such as Codex and Claude Code can inspect repositories, edit files, run commands, write tests, and delegate bounded work to internal subagents. However, as software projects become more complex, developers still have to coordinate multiple agent sessions manually.

A developer may open several Codex windows, assign different tasks, copy implementation results between sessions, ask one agent to review another agent’s work, and repeatedly explain shared context and dependencies. Running several agents at the same time does not automatically make them a team.

This inspired the central question behind MachineFlow:

How can independent coding agents work together like a coordinated software engineering team?

MachineFlow is inspired by how real engineering teams operate. Team members have different roles, own specific tasks, exchange artifacts, request reviews, report blockers, and depend on one another’s outputs while working toward a shared goal.

The visual Logic Graph emerged from the same problem. A single coding agent can often be managed through conversation, but a multi-agent project quickly becomes difficult to understand through terminal windows and chat logs alone. Developers need to see who owns each task, which work depends on another task, what information has been handed off, and where the project is currently blocked.

MachineFlow turns that complexity into a visible and manageable engineering workflow.

What it does

MachineFlow turns multiple independent Codex sessions into one coordinated software engineering team.

Within a MachineFlow project session, each coding agent has:

• an independent Codex session and context
• a defined engineering role
• an assigned task and ownership scope
• its own execution state
• a project-specific message inbox
• access to shared artifacts and decisions
• the ability to request work, review results, and return feedback

For the prototype, MachineFlow demonstrates an implementation-and-review workflow:

Implementer Codex Agent
        ↓
Implementation Artifact
        ↓
Project Queue
        ↓
Reviewer Codex Agent
        ↓
Approve or Request Revision
        ↓
Implementer Codex Agent
        ↓
Validation and Completion

The human developer starts the team from a visual Logic Graph. MachineFlow then coordinates the agents, routes messages and artifacts between them, and updates the graph as work progresses.

The prototype makes the following states visible:

• task assigned
• agent running
• artifact ready
• review requested
• revision requested
• task approved
• validation passed or failed
• project completed

MachineFlow differs from simply opening multiple Codex windows. The agents participate in the same project session, communicate through structured messages, and collaborate around shared tasks and artifacts.

It also operates above vendor-specific subagents. A Codex agent may use its own internal subagents, but MachineFlow treats the complete Codex session as an independent team member. In the future, one MachineFlow team could contain several Codex agents, several Claude Code agents, or a mixture of both.

How we built it

MachineFlow is built as two connected layers: a Python multi-agent runtime and a TypeScript visual workbench.

Multi-agent runtime

The backend prototype uses Python, FastAPI, and asyncio.

Each project receives an isolated ProjectSession. A session contains:

• agent-specific asyncio.Queue inboxes
• a shared runtime event queue
• project tasks and dependencies
• shared artifacts
• running asynchronous agent workers
• project completion state

At the top level, sessions are separated by project ID:

project_sessions: dict[str, ProjectSession]

This prevents messages and runtime state from different projects from being mixed together.

Each agent has its own inbox because a single shared queue would deliver each message to only one competing consumer. Agent-specific queues allow MachineFlow to route a review request specifically to the reviewer and return revision feedback specifically to the implementer.

Agents exchange structured messages such as:

task.assigned
artifact.ready
review.requested
revision.requested
task.approved
agent.failed

A simplified message contains:

@dataclass(frozen=True)
class TeamMessage:
    type: MessageType
    project_id: str
    from_agent: str
    to_agent: str
    task_id: str
    payload: dict[str, Any]

We use three different asynchronous coordination mechanisms for distinct purposes:

asyncio.Queue.join()
→ confirms that queued messages were processed

asyncio.gather()
→ waits for running agent workers to terminate

asyncio.Event
→ indicates that the project workflow reached a final state

This separation is important because an empty queue does not necessarily mean the project is complete. A reviewer may finish processing one message and immediately create a new revision task for the implementer.

Codex integration

Codex performs the actual coding and review work.

MachineFlow assigns each Codex instance a role-specific task packet. The implementer receives the development goal, permitted scope, acceptance criteria, and validation instructions. The reviewer receives the resulting artifact and a separate review contract.

A task packet can contain:

{
  "taskId": "add-input-validation",
  "goal": "Implement input validation and update tests",
  "scope": {
    "read": ["src/**", "tests/**"],
    "write": ["src/validation/**", "tests/validation/**"]
  },
  "acceptanceCriteria": [
    "Invalid input is rejected",
    "Existing valid input remains compatible",
    "All validation tests pass"
  ],
  "validationCommands": [
    "pytest tests/validation"
  ]
}

The Codex instances remain independent, but MachineFlow connects them through project-scoped messages and artifacts.

Visual workbench

The workbench is built with:

• TypeScript
• Next.js
• React
• React Flow
• Zustand
• shadcn/ui

The interface acts as a visual control plane:

Left panel
- project and agent team
- roles and runtime status

Center panel
- Logic Graph
- tasks and dependencies
- live execution state

Right panel
- queue messages
- agent communication
- artifacts and review feedback

Bottom panel
- runtime events
- code changes
- validation results

React Flow represents the relationships among tasks, while Zustand keeps graph state, agent state, messages, and selected artifacts synchronized throughout the workbench.

The Logic Graph is not just a visualization. Its nodes correspond to executable tasks, and its edges describe handoff or dependency conditions such as artifact_ready, revision_requested, and approved.

Challenges we ran into

Defining what makes agents a team

The first challenge was realizing that running several Codex processes in parallel is not enough.

Parallel workers can still remain isolated. A software team requires additional concepts:

• identity
• role
• ownership
• dependency
• message
• artifact
• decision
• review
• blocker
• handoff
• completion evidence

This led us to focus on a team coordination protocol rather than only process execution.

Designing project-scoped communication

We needed multiple agents to communicate without mixing messages from unrelated projects.

Creating one queue for every project was a useful starting point, but one shared queue was not sufficient for directed communication. With multiple consumers, a message would be received by whichever agent consumed it first.

We therefore separated general project coordination from agent-specific inboxes. This allowed messages to remain isolated by project and explicitly addressed to an intended agent.

Distinguishing queue completion from project completion

asyncio.Queue.join() waits until queued items have been acknowledged with task_done(), but that does not guarantee that the engineering workflow is finished.

For example, a reviewer may acknowledge a review request and then create a new revision request. The original queue item is complete, while the project is not.

We solved this by using a separate asyncio.Event for project-level completion and reserving Queue.join() for message-processing synchronization.

Preventing uncontrolled context sharing

Giving every agent access to the full conversation history would increase token usage and introduce irrelevant or outdated information.

We separated shared information into four types:

• Messages for short requests and notifications
• Artifacts for code diffs, schemas, test outputs, and documents
• Decisions for confirmed project choices
• Events for factual execution history

This makes it possible to send each agent only the context required for its current responsibility.

Preventing conflicting code changes

Multiple coding agents can interfere with one another when they modify the same repository at the same time.

The prototype intentionally uses a narrow workflow in which one implementer creates an artifact and one reviewer evaluates it. Future versions will require stronger worktree isolation, explicit write scopes, conflict detection, and controlled integration.

Keeping the prototype focused

MachineFlow could grow into a broad multi-agent development platform, but the hackathon timeline required a much smaller target.

We deliberately postponed:

• distributed message brokers
• persistent workflow storage
• production recovery
• dynamic agent assignment
• cross-machine execution
• a complete IDE
• unrestricted agent-to-agent conversations
• long-term semantic memory

The prototype instead focuses on demonstrating one complete collaboration loop:

Implement → Review → Revise → Validate

Accomplishments that we're proud of

We are proud that the prototype demonstrates cooperation between independent Codex sessions rather than simulated multi-agent behavior inside one prompt.

The most important accomplishments are:

• creating separate Codex agents with distinct roles and contexts
• isolating multi-agent runtime state by project
• routing structured messages between agent-specific queues
• transferring implementation results as reviewable artifacts
• supporting a real revision loop between implementer and reviewer
• distinguishing message completion from project completion
• reflecting runtime states in a visual Logic Graph
• connecting agent execution, queue activity, review feedback, and validation in one workbench

We are also proud that MachineFlow gives the Logic Graph a practical reason to exist. It is not a decorative node editor. It helps a human understand and supervise a software team whose members happen to be autonomous coding agents.

Most importantly, the prototype shows the difference between:

Multiple agent windows

and:

One coordinated multi-agent engineering session

What we learned

We learned that the hardest part of multi-agent software development is not necessarily generating more code.

As individual coding agents become more capable, the difficult problems shift toward coordination:

• how work is decomposed
• how roles are assigned
• how task ownership is enforced
• how dependencies are represented
• how context is routed
• how artifacts are exchanged
• how review feedback returns to the correct agent
• how completion is verified
• how a human understands the entire process

We also learned that visual representation becomes more valuable as the number of agents and dependencies increases. A conversation is effective for one agent, but a graph is more effective for supervising a team.

Another important lesson was that shared conversation is not the same as shared understanding. Agents collaborate more reliably when they exchange typed messages, explicit artifacts, and recorded decisions rather than receiving an ever-growing transcript.

Finally, we learned that existing coding agents do not need to be replaced to create a new multi-agent product. Codex can remain responsible for coding intelligence, while MachineFlow provides the coordination, visualization, communication, and supervision layers around multiple independent Codex instances.

What's next for MachineFlow

The first prototype focuses on two Codex agents collaborating through an implement-and-review loop.

The next step is to expand this into a more complete software team:

Architect Agent
        ↓
Backend Agent + Frontend Agent
        ↓
Integration Agent
        ↓
Reviewer and Validation Agents

Planned capabilities include:

• parallel frontend and backend agents
• architect-led task decomposition
• shared API and design artifacts
• agent-specific Git worktrees
• automatic conflict detection
• persistent project sessions
• durable message and artifact storage
• human approval gates
• dynamic replanning when tasks are blocked
• graph-aware context retrieval
• cost and usage-aware scheduling
• project history and audit trails
• multiple Codex agents in one team
• mixed teams of Codex and Claude Code agents
• adapter support for additional coding-agent runtimes

Our long-term vision is:

MachineFlow becomes the visual operating system for software engineering teams composed of humans and independent coding agents.

MachineFlow does not simply run more agents. It gives them roles, relationships, shared goals, structured communication, and a way to work together as one engineering team.

Built With

• asyncio
• codex
• fastapi
• git
• gpt-5.6
• next.js
• node.js
• openai
• pydantic
• python
• reactflow
• shadcn/ui
• typescript
• zustand