Async Code Agent: How to Run Multiple AI Coders in Parallel Without Losing Your Mind

A practical, jargon-free guide to setting up, using, and extending the open-source Async Code Agent platform—built for developers who want AI help on many files at once, not one file at a time.

Table of Contents

  1. Why Parallel AI Coding Matters
  2. What Async Code Agent Actually Does
  3. Core Features in Plain English
  4. Quick-Start: From Zero to Running in Ten Minutes
  5. Step-by-Step Daily Workflow
  6. Architecture at One Glance
  7. Development Mode vs. Production Mode
  8. Common Questions (FAQ)
  9. Troubleshooting Checklist
  10. Next Steps & Extending the Platform

1. Why Parallel AI Coding Matters

If you have ever asked Claude Code or any other AI assistant to refactor a large codebase, you know the drill:

  • Queue one task.
  • Wait.
  • Review the diff.
  • Repeat.

Async Code Agent flips this sequence on its head. Instead of a single queue, you get a dashboard where every task—lint fixes, unit-test generation, dependency upgrades, security patches—runs in its own isolated container. While the AI works on file A, another container can already be working on file B. You spend your time reviewing and merging, not waiting.

2. What Async Code Agent Actually Does

Think of it as a task runner with three extra powers:

  1. Many agents at once—each task spins up its own AI model (right now Claude Code, but you can plug in others).
  2. Built-in Git workflow—clones, branches, commits, and opens pull requests automatically.
  3. Side-by-side comparison—see two diffs on the same screen and decide which one you like.

All of this happens through a clean web interface that looks and feels like the original Codex playground.

3. Core Features in Plain English

Feature What It Means for You Real-World Example
Multi-Agent Support You can pick different AI models for the same task. Run Claude Code and another model on the same function, then keep the cleaner output.
Parallel Task Management Multiple tasks run at the same time, each in its own container. Upgrade React in one container, add TypeScript in another, and never worry about conflicts.
Codex-Style Web UI A simple web page to start, track, and compare tasks. No command-line flags to remember—just fill out a form and press “Run.”
Agent Comparison Diffs from two tasks appear next to each other. Instantly spot which model removed the most unused imports.
Containerized Execution Each job runs in a fresh Docker container. If a dependency install breaks, only that container fails; the rest keep working.
Git Integration Automatically clones the repo, creates a branch, commits, and opens a PR. You review and click “Merge” in GitHub—no manual git push.
Self-Hosted Runs on your laptop or on any server you control. Keep sensitive code inside your own network.

4. Quick-Start: From Zero to Running in Ten Minutes

4.1 Prerequisites

  • Docker and Docker Compose installed (any recent version works).
  • An Anthropic API key if you intend to use Claude Code.
  • (Optional) A Supabase account if you want persistent storage across restarts.

4.2 Clone and Configure

# 1. Clone the repository
git clone <repository-url>
cd async-code

# 2. Copy the environment template
cp server/.env.example server/.env

# 3. Edit server/.env
# Add your ANTHROPIC_API_KEY.
# If you use Supabase, also add SUPABASE_URL, SUPABASE_ANON_KEY, and SUPABASE_SERVICE_ROLE_KEY.

4.3 Build and Launch

docker-compose up --build -d

Visit:

  • Frontend: http://localhost:3000
  • Backend API: http://localhost:5000

4.4 Optional Supabase Setup

  1. Create a new project in the Supabase dashboard.
  2. Open the SQL editor and run the contents of db/init_supabase.sql.
  3. Copy the project URL, anon key, and service role key from Project Settings → API into server/.env.

5. Step-by-Step Daily Workflow

Step 1: Connect GitHub

Open http://localhost:3000. On first visit, the UI asks for a GitHub personal access token with repo scope. Paste it and click Save.

Step 2: Choose Repository

Fill in:

owner/repo-name
branch: main

The platform immediately clones the repo into a fresh volume.

Step 3: Pick an Agent

The dropdown defaults to Claude Code. Other agents appear here once you register them.

Step 4: Describe the Task

In plain English:

Refactor all print() statements in utils.py to use the logging module and add unit tests.

Click Run Task.

Behind the scenes:

  1. A container starts.
  2. The agent checks out a new branch.
  3. The AI edits the code and runs tests.
  4. Results stream back to the web UI.

Step 5: Compare & Merge

  • Click Diff to see the changes.
  • Click Create PR to push the branch and open a pull request on GitHub.
  • If you ran two agents on the same task, the Compare view lines up both diffs so you can cherry-pick the best parts.

6. Architecture at One Glance

  • Frontend

    • Next.js, TypeScript, TailwindCSS
    • REST calls to the backend

  • Backend

    • Python Flask
    • Routes: /tasks, /runs, /agents, /git
    • Uses Docker SDK to start containers

  • Agents

    • Currently Claude Code (Anthropic)
    • Pluggable interface: drop a Python file into server/agents/

  • Task Execution

    • Each task → one Docker container
    • Container image includes Python, Node, or other runtimes you need

  • Data Storage

    • Optional Supabase Postgres for tasks, runs, and outputs
    • Falls back to SQLite when Supabase is not configured

7. Development Mode vs. Production Mode

7.1 Development Mode

Run services separately for faster feedback.

# Terminal 1: Backend
cd server
python main.py           # http://localhost:5000

# Terminal 2: Frontend
cd async-code-web
npm install
npm run dev              # http://localhost:3000

Hot-reload works on both sides.

7.2 Production Mode

  1. Edit server/.env:

    FLASK_ENV=production
FLASK_DEBUG=False
  2. Export the Node environment:

    export NODE_ENV=production
  3. Build and start:

    docker-compose up --build -d
  4. Watch logs:

    docker-compose logs -f

8. Common Questions (FAQ)

Q1: Do I need a GPU?
No. The AI models run in the cloud. Your local machine only schedules containers; CPU and RAM usage are minimal.

Q2: My company blocks GitHub. Can I use GitLab?
Yes. Mirror your repository to an internal GitLab instance and change the remote URL in the UI.

Q3: How do I add another AI model?
Create a new Python file in server/agents/, implement the run(task_context) function, and register the agent in agents.yaml. The README in that folder contains a minimal example.

Q4: A task failed. How do I debug?
Click the Logs tab on the task card. You will see the same stdout and stderr you would get from docker logs.

Q5: Can I limit CPU or memory per container?
Yes. Edit the docker-compose.yml file and add resource constraints under the deploy key for the agent service.

9. Troubleshooting Checklist

Symptom Quick Fix
“Container cannot start” Ensure Docker daemon is running and your user is in the docker group.
“Anthropic key invalid” Check for trailing spaces in server/.env.
“Repository clone fails” Confirm the GitHub token has repo scope and the repository URL is correct.
“Cannot see diff” Refresh the page; the diff loads after the container exits.

10. Next Steps & Extending the Platform

  1. Custom Runners
    Add a Rust or Go agent by following the same interface used for Claude Code.

  2. Notification Hooks
    Append Slack, Teams, or email alerts by implementing a new Notifier class.

  3. Cost Control
    Set per-task spending caps inside the agent container; log usage to Supabase for monthly reports.

  4. CI Integration
    Trigger Async Code Agent tasks from GitHub Actions by calling the backend API endpoint /api/v1/tasks.

Final Thoughts

Async Code Agent turns the once-linear process of AI-assisted coding into a parallel pipeline. Instead of babysitting a single long-running job, you orchestrate many small ones, review the outcomes, and merge the best. Whether you are maintaining one repository or fifty, the platform keeps the cognitive load low and the throughput high.

Clone it, run it, and let the agents do the waiting for you.