We Gave Our AI Coding Agents an Office. These Are the House Rules.

One coding agent on your repo is a pair programmer. Four agents on the same repo, with no rules, is a merge conflict with a token bill.

The failure modes are predictable. Two agents edit the same file. One makes a failing test pass by deleting it. Another hits a blocked API and writes a workaround instead of asking. Nobody knows which PR should land first.

So we built JSM HQ, an open-source pixel-art office where a lead agent plans the work and a team of worker agents builds it on your repo. This post is less about the pixels and more about the rules underneath them. You can steal the rules even if you never install HQ.

If you run more than one agent at a time, or want to, this is for you.

The office, running on demo data. Michael leads, Dwight and Jim build. Jim's card is red because he's waiting on a decision.

The setup in one paragraph

You run HQ inside a git repo that has a GitHub remote. You pick a lead and some workers, and each one runs Claude Code or Codex. HQ gives every agent its own full clone of the repo and, by default, its own Docker Sandbox, a small VM that can't reach the rest of your machine. The agents talk to each other through an MCP server called hq. HQ watches GitHub through your gh login and turns all of it into an office you can watch.

Now the rules.

Rule 1: The lead never writes app code

The lead's job is to plan and assign. It creates boards (one per phase, for example), splits the work into tasks, and hands each task to a free worker. That's it.

This sounds wasteful. Why pay for an agent that doesn't code?

Because the moment a planner starts coding, it stops planning. It loses track of who's doing what, and it starts editing files a worker already owns. Keeping one agent with the whole picture and no keyboard is the cheapest coordination we found.

The lead gets a different set of tools from the workers to match:

lead:    list_workers, get_status, list_tasks, create_board, create_task,
         update_task, assign_task, send_message, ask_user, request_access

worker:  get_my_task, set_my_status, list_workers, get_status, list_tasks,
         send_message, ask_user, request_access

Only the lead can create or assign tasks. Workers can only pick up the one they were given.

Rule 2: One task = one branch = one PR

Every task is small enough to land as a single pull request. The lead writes each task with two things attached: the files it may edit and a clear done-when.

A worker's loop looks like this:

1. Call get_my_task.
2. git pull origin main and create a branch.
3. Do the work.
4. Open a PR titled [TASK-ID] Short title.
5. Call set_my_status with in-review and the PR number.

That [TASK-ID] prefix isn't cosmetic. HQ polls GitHub about every 20 seconds and uses it to match each PR to its task. New review comments go back to the PR's author to fix. A merge marks the task done.

Rule 3: Edit only the files your task lists

This rule answers a question we keep getting: what happens when two agents need the same file?

Mostly, they don't get the chance. The lead decides up front which files each task may touch, so two parallel tasks shouldn't claim the same module. If a worker discovers mid-task that it needs another file, it doesn't just open it. It asks the lead with send_message.

When overlap does happen, it gets caught at the PR stage. The lead decides the order PRs should land in and flags any PR that blocks another. If a PR conflicts with main, HQ tells its author to fix it.

So the answer is both: scope is serialized at planning time, and anything that slips through is reconciled at review.

Rule 4: Every agent gets its own desk

"Desk" here means three concrete things:

• Its own clone at ~/.jsmhq/<project>/<agent>/. Your working folder is never touched.
• Its own instructions. HQ writes a .jsmhq-role.md file with the agent's role, the team, the rules and its tools, and keeps it out of git through .git/info/exclude.
• Its own sandbox. On macOS and Linux each agent also runs in a tmux session, so it keeps working if you close the browser. You can watch any of them with tmux attach -t hq-<project>-<agent>.

Teammates can't see each other's files or terminals. They talk only through messages. That forced isolation is what makes parallel work safe.

Dwight's drawer: his live Claude Code session on the right, and three requests his sandbox blocked, each waiting for Allow or Dismiss.

Rule 5: Ask, don't work around

This is the rule we care about most, and it's where the red desk comes from.

Sandboxes use a network policy you pick once. The recommended one, balanced, allows AI services, package registries and GitHub, and blocks everything else. Agents will hit that wall all the time: a library's docs, a third-party API.

An agent that's been told "get it done" will try to route around a block. Ours are told the opposite. Here's the actual line from the role file HQ writes:

If a request you need is blocked (a docs page or an API: usually a 403 saying
'Approval required for <host>'), call request_access with the domain and why,
then continue with other work until HQ tells you it was answered.
Never work around the block.

When that happens, the agent's card turns red and you get three buttons: Allow for this agent, Allow for everyone, Deny. Allowing adds a rule for that one sandbox. Your base policy is never touched.

The same goes for anything outside the sandbox. Need a database created or an API key added? The agent calls ask_user with exact steps, and it names the variable, never the secret. Everything waiting on you collects in one Action items list in the top bar.

Keys get the same treatment. Service keys go into Docker Sandboxes' secret store, and the sandbox's proxy adds them to matching requests, so the key itself never enters the VM. HQ never stores key values and never reads your env files.

Rule 6: HQ never merges

Agents open PRs. Reviews run through the tool you pick in Settings → Workflow: CodeRabbit, Greptile, Copilot, yourself, or your own. When a PR passes, the lead is told it's ready.

Then you merge, on GitHub.

That's the default, and it's deliberate. Review is where you catch the agent that made a test pass by deleting it. If you trust your review pipeline, there's a "Who merges" switch in Settings → Workflow that hands merging to the lead, one PR at a time. HQ itself still never merges.

Steal the rules without installing anything

You don't need HQ to get most of the benefit. If you run parallel agents today, paste something like this into your CLAUDE.md or AGENTS.md:

## Rules for parallel work
- One task = one branch = one PR. Title PRs `[TASK-ID] Short title`.
- Edit only the files your task lists. Need another file? Stop and ask.
- If a website or API is blocked, say so and continue with other work.
  Never work around the block.
- Never put secret values in messages or code. Name the variable instead.
- Never merge. A human merges after review.

The office just makes those rules visible and enforces the plumbing around them.

Try it

You'll need Node.js 20+, git, the GitHub CLI, tmux (macOS and Linux), Docker Sandboxes, and a Claude or ChatGPT account for the agents. The getting-started guide says the first setup takes about 15 minutes, mostly installing tools. HQ also shows a setup checklist with the exact command for anything missing.

From your project folder:

npx @therealjsmastery/jsm-hq@latest

Pick your team on the welcome screen, press Start team, then message the lead. The guide suggests a first message like:

Read plan.md. Create a board for Phase 1, plan its tasks with the files
each one touches, and assign them.

The honest limits

• Platform support. Sandboxes need macOS 14+ on Apple silicon, Ubuntu 24.04+, or Windows 11. Windows is experimental: there's no tmux, so agents stop when HQ stops. Elsewhere you can run agents in Local mode, without the sandbox isolation.
• Usage adds up. Every agent runs on your own Claude or ChatGPT account. Four agents use your plan's limits roughly four times as fast as one.
• Rules reduce conflicts, they don't remove them. A lead can still plan two tasks that collide. Review is still your job.
• Small tasks work best. Our rule of thumb (an opinion, not a benchmark): if a task can't be described with a file list and a done-when, it's too big for one agent and should be split.

What's next

The code is MIT-licensed on GitHub, and the How it works doc covers everything we skipped here: MCP servers per agent, port forwarding, app variables, and what HQ saves where.

We're curious how other people split work between agents. Do you plan file ownership up front, or let branches collide and sort it out at review?

The full walkthrough is on the JavaScript Mastery YouTube channel.