{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-parallel-agents",
  "slug": "parallel-agents",
  "title": "Keep parallel agent work visible and bounded",
  "summary": "A parallel workspace is not useful because it looks busy. It is useful when each lane has a job, a boundary, a check, and a visible trail. Start by planning the split. Then open the workspace that makes that split easy to supervise.",
  "category": "Execution",
  "tags": [
    "parallelism",
    "ownership",
    "orchestration"
  ],
  "sources": [
    {
      "label": "Codex workflows companion",
      "url": "https://lapis-fossil-vsbc.here.now/#parallel-agents"
    },
    {
      "label": "Published workshop recording",
      "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
    }
  ],
  "sourceUnits": [
    "src/content/final/chunk-06-visible-parallel-agents.md",
    "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them",
    "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them/Start Fresh For The Task",
    "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them/Split By Boundaries, Not By Vibes",
    "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them/Keep The Agents Visible",
    "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them/Use A Manager Thread",
    "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them/Copyable Prompt: Parallel Work Plan",
    "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them/Copyable Prompt: Lane Setup",
    "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them/Make Progress Legible",
    "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them/Save The Layout Only After It Repeats",
    "src/lib/content/sections.ts",
    "src/lib/content/sections.ts#parallel-agents",
    "src/lib/content/sections.ts#recordingSpans"
  ],
  "collection": "codex",
  "categoryId": "execution",
  "wordCount": 887,
  "url": "/topics/codex-parallel-agents/",
  "markdownUrl": "/markdown/codex-parallel-agents.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-parallel-agents.json",
  "headings": [
    {
      "id": "start-fresh-for-the-task",
      "text": "Start Fresh For The Task",
      "level": 2
    },
    {
      "id": "split-by-boundaries-not-by-vibes",
      "text": "Split By Boundaries, Not By Vibes",
      "level": 2
    },
    {
      "id": "keep-the-agents-visible",
      "text": "Keep The Agents Visible",
      "level": 2
    },
    {
      "id": "use-a-manager-thread",
      "text": "Use A Manager Thread",
      "level": 2
    },
    {
      "id": "copyable-prompt-parallel-work-plan",
      "text": "Copyable Prompt: Parallel Work Plan",
      "level": 2
    },
    {
      "id": "copyable-prompt-lane-setup",
      "text": "Copyable Prompt: Lane Setup",
      "level": 2
    },
    {
      "id": "make-progress-legible",
      "text": "Make Progress Legible",
      "level": 2
    },
    {
      "id": "save-the-layout-only-after-it-repeats",
      "text": "Save The Layout Only After It Repeats",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Keep parallel agent work visible and bounded\n\nA parallel workspace is not useful because it looks busy. It is useful when each lane has **a job, a boundary, a check, and a visible trail**. Start by planning the split. Then open the workspace that makes that split easy to supervise.\n\n## Start Fresh For The Task\n\nDo not begin by hunting for the perfect saved layout. Begin with the **current phase of work**: what needs design, what needs implementation, what needs verification, and what can safely happen at the same time.\n\nA dashboard task, a migration, a game level, and a new project do not need the same shape. **Ask for the split that fits the task in front of you.**\n\nFor a dashboard:\n\n- one lane designs the data cards\n- one lane checks API shape and sample data\n- one lane writes component tests\n- one lane reviews empty, loading, and error states\n\nFor a migration:\n\n- one lane maps the source schema\n- one lane maps the destination schema\n- one lane writes verification queries\n- one lane drafts rollback notes\n\n## Split By Boundaries, Not By Vibes\n\nEach lane needs a job, allowed files, files to avoid, and proof. If two lanes need the same files, they are **not parallel yet**.\n\n> How can we accomplish this task with multiple agents, where they each have their own responsibility, and they each have their own testing, they can work in parallel, usually in the same branch, honestly.\n>\n> — John Lindquist\n\n| Lane | Owns | Avoids | Proof |\n|---|---|---|---|\n| UI lane | `src/routes/dashboard/**`, component snapshots | API contracts, migration files | screenshot and component checks |\n| Data lane | query helpers, fixtures, schema mapping | visual components | query tests |\n| Test lane | new regression tests | production logic except test hooks | failing-before / passing-after log |\n| Review lane | risk notes, integration checklist | code edits | written review with blockers |\n\n## Keep The Agents Visible\n\n**Visible work is easier to correct.** You can inspect the history, compare outputs, step into one lane, or stop a bad direction before it spreads.\n\nHidden background work can be useful, but it removes the trail you need when the next run should be better. If the task is risky, keep the lanes where you can watch them.\n\n> When I see agents spawn up in background threads, and I don't know what they're doing, and I can't, like, look at some of the history and tool calls and everything. I don't know how it could improve next time.\n>\n> — John Lindquist\n\n## Use A Manager Thread\n\n**One thread owns the plan.** Other lanes execute bounded work. The manager does not need to do every task. It needs to remember the split, check progress, catch conflicts, and decide when to merge, redirect, or stop.\n\nManager responsibilities:\n\n- restate the project goal\n- divide work into lanes\n- assign file boundaries\n- name the verification for each lane\n- tell each lane which other lanes exist\n- check progress before merging ideas\n- stop any lane that crosses its boundary\n\n## Copyable Prompt: Parallel Work Plan\n\n```text\nWe need to plan parallel agent work for this software task.\n\nTask:\n[describe the feature, fix, migration, or review]\n\nCurrent phase:\n[planning / implementation / debugging / visual review / verification]\n\nProject facts:\n- active areas:\n- stable areas to avoid:\n- commands/tests available:\n- risky files:\n- expected output:\n\nCreate a parallel work plan.\n\nReturn:\n1. the smallest useful number of lanes\n2. the responsibility of each lane\n3. exact file or directory boundaries for each lane\n4. what each lane must not touch\n5. the verification each lane must run\n6. the manager check-in schedule\n7. the prompt to initialize each lane\n\nPrefer fewer lanes if file conflicts are likely.\nDo not start implementation yet.\n```\n\n## Copyable Prompt: Lane Setup\n\n```text\nYou are Lane [name].\n\nGoal:\n[one responsibility]\n\nAllowed files:\n[list]\n\nDo not touch:\n[list]\n\nOther lanes running:\n- [lane]: [scope]\n- [lane]: [scope]\n\nBefore editing:\n- inspect only your allowed area\n- restate the files you expect to touch\n- name the verification you will run\n\nAfter editing:\n- summarize changes\n- list files changed\n- run verification\n- report any boundary conflicts\n```\n\n## Make Progress Legible\n\nUse agents to make proof easier to produce: screenshots, before/after numbers, test logs, release notes, and short visual summaries. The goal is not noise. The goal is **reviewable impact**.\n\nBefore/after performance note:\n\n```text\nBefore:\nDashboard loaded sample account in 4.8s.\n\nAfter:\nDashboard loaded sample account in 1.9s.\n\nProof:\nTrace attached, test command included.\n\nChange:\nCached account summary query and removed duplicate fetch.\n```\n\nVisual progress note:\n\n```text\nWhat changed:\nReplaced manual export flow with a reviewed batch job.\n\nWhy it matters:\nRemoves three support steps.\n\nProof:\nScreenshot, smoke test, rollback note.\n```\n\n## Save The Layout Only After It Repeats\n\n**A reusable layout is earned.** If the same task shape appears three times with the same lane split, checks, and review surface, turn it into a saved workspace, script, or small helper.\n\nUntil then, start fresh and ask for the split.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#parallel-agents)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
}
