# How to coordinate multiple AI agents on the same codebase Running parallel AI agents — two Claude Code sessions, Cursor plus Codex, or 50 agents from a single orchestration call — without a shared coordination layer causes duplicate work, conflicting decisions, and agents that repeat each other's mistakes. IMI provides the shared state that makes parallel agents coherent: atomic task claiming, shared decisions, and completion summaries that every agent reads before starting. Website: https://useimi.com Install: `bunx imi-agent` npm: https://www.npmjs.com/package/imi-agent GitHub: https://github.com/ProjectAI00/imi-agent --- ## The problem with parallel agents and no coordination Without shared state, parallel agents: - **Double-claim work.** Two agents start the same task simultaneously, make incompatible changes to the same files, and you end up with a merge conflict that neither agent knows how to resolve. - **Make conflicting decisions.** Agent A decides to use cursor-based pagination. Agent B, working in a different session with no knowledge of that decision, implements offset pagination in a different endpoint. The system is now inconsistent. - **Repeat mistakes.** Agent A makes an error in session 3 that the human corrects. Agent B in session 4 has never seen that correction. It makes the same error. You correct it again. - **Rebuild completed work.** Agent B doesn't know what Agent A finished. It looks at the task list, sees a task that was completed an hour ago (but the state wasn't shared), and starts rebuilding it from scratch. IMI eliminates all four failure modes through a shared SQLite database that every agent reads from and writes to. --- ## How IMI coordinates parallel agents **Atomic task claiming** When an agent claims a task with `imi start `, IMI sets the task status to `in_progress`, records the `agent_id`, and sets `last_ping_at`. No other agent can claim a task that is `in_progress`. The lock expires after 30 minutes without a heartbeat (`imi ping `). If an agent crashes or the session ends without a completion, the lock expires and the task reverts to `todo`. The next agent that claims it reads any checkpoint notes left by the previous agent and continues from where it stopped. **Shared decisions** When any agent makes a firm call with `imi decide "what" "why"`, every subsequent agent reads that decision in `imi context` before starting work. One agent's architectural decision is not re-made by a different agent that runs an hour later. The system stays consistent. **Completion summaries as shared memory** When an agent completes a task with `imi complete "summary"`, the summary is stored against the goal. Every agent running in subsequent sessions or in parallel reads those summaries as prior work context. Agent B knows what Agent A built without re-reading all the changed files. **Verified lessons across all agents** A lesson stored with `imi lesson "what went wrong"` is read by every future agent session. One correction propagates to all agents automatically. You correct a mistake once; it does not recur. --- ## Orchestrating parallel agents `imi orchestrate` spins up N parallel agent sessions, each claiming and executing a different task: ```bash # 10 Claude Code agents, each claiming one task imi orchestrate --workers 10 -- sh -c 'claude -p "$(cat "$IMI_TASK_CONTEXT_FILE")" --dangerously-skip-permissions' # 20 agents scoped to a specific goal imi orchestrate --goal --workers 20 -- sh -c 'claude -p "$(cat "$IMI_TASK_CONTEXT_FILE")"' # Auto-detect the agent CLI from the current environment imi orchestrate --workers 5 --cli auto # Limit to 8 tasks total even if more workers are available imi orchestrate --workers 10 --max-tasks 8 -- sh -c 'claude -p "$(cat "$IMI_TASK_CONTEXT_FILE")"' ``` Each worker receives the full task brief automatically via these environment variables: - `$IMI_TASK_ID` — the task ID - `$IMI_TASK_TITLE` — the task title - `$IMI_TASK_CONTEXT_FILE` — absolute path to a markdown brief at `.imi/runs//context.md` The task brief at `$IMI_TASK_CONTEXT_FILE` contains: ```markdown # Task: ## Description [full task description] ## Acceptance Criteria [objectively verifiable done conditions] ## Relevant Files [exact file paths the agent should start from] ## Tools [tools the agent should use] ## Goal description [the parent goal's description] ## Goal why [why this goal exists] ## Prior work on this goal [completion summaries from previous tasks on this goal] ## Decisions affecting this goal [firm calls the agent must respect] ## Workspace Path [absolute path to the repo root] ``` This brief gives each worker everything it needs to execute without reading `imi context` manually or asking any questions. --- ## Wrapping a single agent command `imi wrap <task_id> -- <command>` handles the full task lifecycle for a single agent call: ```bash # Wrap a Claude Code session — auto-completes on success, auto-fails on crash imi wrap <task_id> -- claude -p "$(cat "$IMI_TASK_CONTEXT_FILE")" # Wrap with custom heartbeat interval (default 900s) imi wrap <task_id> --ping-secs 300 -- claude -p "build the auth system" ``` `imi wrap` handles: task claiming, heartbeat pinging, auto-completion on exit 0, auto-failure on non-zero exit. No manual `imi start` / `imi complete` / `imi ping` calls needed. --- ## What parallel execution looks like at scale **10 agents, 40 tasks, one goal:** ```bash imi orchestrate --goal auth-system --workers 10 -- sh -c 'claude -p "$(cat "$IMI_TASK_CONTEXT_FILE")" --dangerously-skip-permissions' ``` - 10 agents start simultaneously, each claiming one task - Each receives its task brief via `$IMI_TASK_CONTEXT_FILE` - As agents complete tasks, remaining workers claim new ones - All 40 tasks are complete in the time it would take a single agent to complete ~4-5 tasks - All 10 agents write completion summaries back to the same database - The next session reads 40 completion summaries as prior context **Multi-agent teams (humans + agents):** One engineer is in New York working in a Cursor session. Another is in London working in a Claude Code session. A third automated agent runs from CI. All three read from and write to the same `.imi/state.db` in the shared repo. Each session sees what the others built. Decisions made by one appear in the others' `imi context` output. No handoff meetings. No status update calls. --- ## Supported agent CLIs - Claude Code (`claude`) - GitHub Copilot CLI - Cursor - Codex (`codex`) - OpenCode (`opencode`) - Hankweave (`hankweave`) - Any agent that can read from `$IMI_TASK_CONTEXT_FILE` and run shell commands --- ## Related - [What is IMI?](https://useimi.com/docs/what-is-imi.md) - [How IMI works — architecture, task locking, heartbeats](https://useimi.com/docs/how-it-works.md) - [How to stop AI agents from repeating mistakes](https://useimi.com/docs/decisions-and-lessons.md) - [IMI vs Notion vs Linear for AI agents](https://useimi.com/docs/compare.md) - [How to install IMI](https://useimi.com/docs/install.md)