BranchMind

Turn one product goal into a coordinated team of Codex agents working in parallel across isolated, dependency aware GitHub branches.

Comment

Inspiration

Software projects rarely fail because people lack ideas. They fail because work is divided poorly, contributors receive too much irrelevant context, dependencies are discovered too late, and integration becomes a manual bottleneck.

We imagined BranchMind as an AI-native engineering organization. A user provides one product goal, and BranchMind transforms it into focused specialist assignments. Each Codex agent works in an isolated GitHub branch, independent work runs concurrently, dependent work waits for the correct outputs, and successful contributions return as tested pull requests for human review.

Our goal was not to create another interface that merely sends prompts to a coding model. We wanted to build the orchestration layer required to make multiple coding agents operate like a coordinated engineering team.

What it does

BranchMind converts one product goal into an executable, dependency-aware workstream graph.

It:

  • Uses GPT-5.6 through the Codex CLI to decompose a requirement into specialist workstreams.
  • Validates workstream keys, dependency references, self-dependencies, and cycles.
  • Compiles a focused context package for each agent instead of sending every agent the entire project description.
  • Estimates context-token savings for each specialist assignment.
  • Creates isolated GitHub branches from an exact base commit.
  • Runs specialist Codex agents inside temporary Git worktrees.
  • Executes independent workstreams concurrently while preserving declared dependencies.
  • Incorporates completed dependency branches before starting downstream work.
  • Runs tests, linting, and a production build before accepting an agent’s changes.
  • Commits and pushes real code changes.
  • Opens real GitHub pull requests for successful workstreams.
  • Displays branches, changed files, quality gates, failures, blocked workstreams, concurrency, and pull-request links in one interface.
  • Keeps humans in control of final review and integration.

BranchMind does not simulate agent activity. The branches, commits, checks, failures, and pull requests displayed by the application correspond to real repository operations and GitHub artifacts.

How we built it

BranchMind is built with Next.js, React, TypeScript, Node.js, Zod, Vitest, the Codex CLI, Git, GitHub CLI, and GitHub Actions.

The system is divided into several focused layers:

  1. Planning engine

A structured prompt asks Codex to produce a typed project plan containing objectives, deliverables, acceptance criteria, context needs, and dependencies. Zod validates the response, while a graph validator rejects duplicate keys, missing dependency targets, self-dependencies, and circular dependencies.

  1. Focused-context compiler

Each workstream receives only its relevant objective, deliverables, acceptance criteria, context needs, project summary, and declared dependency outputs. The compiler also creates deterministic fingerprints and estimates how many context tokens are avoided.

  1. GitHub workspace provisioner

BranchMind uses the locally authenticated GitHub CLI to create deterministic agent/* branches from an exact base commit SHA. Provisioning is idempotent, so repeated requests do not create conflicting duplicate branches.

  1. Isolated execution engine

Every specialist agent runs inside a temporary Git worktree. BranchMind invokes the locally authenticated Codex CLI from the server without exposing Codex or GitHub credentials to the browser.

  1. Dependency-aware scheduler

The scheduler identifies every currently runnable workstream and executes independent assignments concurrently. A downstream workstream starts only after all of its dependencies complete successfully. Its isolated worktree then incorporates the dependency branches before the downstream agent begins implementation.

  1. Quality and delivery pipeline

BranchMind detects actual file changes and runs the project’s tests, lint checks, and production build. Only validated changes are committed and pushed. Successful workstreams become real pull requests, which are independently checked again through GitHub Actions.

  1. Product interface

The interface provides project intake, generated workstreams, focused assignments, dependency information, context-efficiency metrics, isolated branch creation, full-team execution, failure propagation, quality-gate results, and direct links to the resulting pull requests.

Challenges we ran into

The hardest challenge was moving from an impressive-looking prototype to a system that performed genuine engineering work.

Creating a GitHub branch is not the same as running an agent. We had to build isolated worktrees, invoke Codex inside the correct repository state, detect actual file changes, execute quality gates, commit safely, push the correct branch, and open a pull request.

Parallel execution introduced another challenge. Running every agent simultaneously would violate dependencies, while running every agent sequentially would waste time. We implemented a dynamic scheduler that runs only the currently eligible workstreams concurrently and blocks downstream work when a required dependency fails.

We also encountered practical engineering problems:

  • Resolving Windows executables safely.
  • Launching Git, npm, Codex, and GitHub CLI commands without a shell.
  • Preventing command-injection risks.
  • Handling idempotent and concurrent GitHub branch creation.
  • Cleaning up temporary worktrees after both success and failure.
  • Incorporating dependency branches into downstream worktrees.
  • Distinguishing genuine failures from assignments already satisfied by existing code.
  • Propagating failures so unsafe downstream work cannot continue.
  • Keeping a browser interface synchronized with long-running server execution.
  • Producing reliable builds across local Windows and GitHub Actions environments.

These challenges forced us to treat agents as real engineering workers operating under strict repository, dependency, and validation constraints.

Accomplishments that we're proud of

We are proud that BranchMind completed a real multi-agent engineering workflow rather than presenting simulated results.

In our end-to-end demonstration:

  • A Runtime Diagnostics specialist and a Capabilities Diagnostics specialist were independent and executed concurrently.
  • Each specialist produced an isolated branch, implementation, focused contract test, commit, and pull request.
  • A dependent Diagnostics Summary specialist waited for both earlier workstreams.
  • Its branch incorporated both dependency implementations before adding the summary endpoint.
  • Every pull request passed the independent GitHub Actions quality gate.
  • The final contributions were reviewed and integrated into the unified main branch.
  • The resulting runtime, capabilities, and summary APIs all operated from the integrated product.

The real pull requests are available here:

We are also proud of:

  • Deterministic dependency-graph validation.
  • Focused context packages with measurable context reduction.
  • Real concurrent execution for independent workstreams.
  • Safe process invocation without a command shell.
  • Automatic cleanup of temporary Git worktrees.
  • Quality gates before commits and pull requests.
  • Independent validation through GitHub Actions.
  • Failure propagation that blocks unsafe downstream work.
  • Honest handling of agents that produce no changes.
  • Automated tests covering planning, context compilation, workspace provisioning, execution, scheduling, and API contracts.

What we learned

We learned that useful multi-agent software development is primarily an orchestration problem.

Giving several agents the same prompt is not enough. Agents need:

  • Clear ownership boundaries.
  • Focused, non-overlapping context.
  • Explicit deliverables and acceptance criteria.
  • Isolated working environments.
  • Valid dependency information.
  • Observable validation results.
  • A reliable integration protocol.
  • Human governance over final decisions.

We also learned that parallelism should be determined by the dependency graph rather than an arbitrary number of workers.

A workstream becomes eligible for execution only after every declared dependency has completed successfully. This allows BranchMind to run independent work concurrently while preventing downstream agents from operating on incomplete or invalid foundations.

This model lets BranchMind maximize safe concurrency without sacrificing correctness.

We also learned that failure is valuable information. If an agent fails validation, produces no required changes, or depends on unsuccessful work, BranchMind must report that state honestly instead of manufacturing a successful result.

Most importantly, human governance remains essential. Agents can plan, implement, test, and prepare pull requests, but humans should retain authority over product direction, security-sensitive actions, code review, and final integration.

What's next for BranchMind

Our next priority is making execution durable, observable, and production-ready.

We plan to add:

  • Persistent server-side execution history.
  • Resumable agent-team runs.
  • Live progress streaming instead of one long synchronous browser request.
  • Dedicated reviewer agents for correctness, security, tests, and requirement coverage.
  • An integration-lead agent that compares implementations and prepares a unified candidate.
  • Recursive decomposition when a generated workstream remains too large.
  • Repository-aware context retrieval based on affected files and architecture.
  • Durable multi-user project workspaces.
  • Authentication and authorization for shared projects.
  • GitHub App integration for hosted deployments.
  • Cost, latency, concurrency, and context-efficiency analytics.
  • Human approval gates for sensitive actions and final merges.
  • Better recognition of assignments already satisfied by the repository.
  • Recovery and retry controls for failed or interrupted workstreams.

The long-term vision is for BranchMind to become an operating system for AI-native software teams: one place where people contribute direction and judgment while coordinated specialist agents transform those decisions into validated, reviewable software.

Built With

Share this project:

Updates