# Claude Code Projects: How a Single AI Orchestrates a Team of Autonomous Agents > A deep dive into Claude Code Projects: Coordinator and Threads architecture, parallel branches, shared memory via MEMORY.md, and cloud agent management. With the release of **Claude Code Projects**, AI-assisted development is shifting from the *"one developer — one chat"* paradigm to full-fledged **multi-agent orchestration**. Previously, solving large, complex tasks required engineers to manually open multiple terminal sessions, copy context between them, track Git branches, and stitch results together themselves. In the new model, the lead AI handles all dispatching. You formulate a single overarching strategic goal, and Claude takes charge: - **Decomposes work:** breaks down the large-scale goal into isolated subtasks. - **Orchestrates flows:** launches parallel cloud sessions (**Threads**). - **Controls context:** synchronizes decisions via shared project memory (`MEMORY.md`). - **Verifies results:** runs tests, checks build status in CI, and prepares final Pull Requests. > [!NOTE] > **Autonomy independent of your local machine:** Workflows (Threads) run in isolated Anthropic cloud containers. They continue executing tests and writing code even when your laptop lid is closed, and you can check their status from your smartphone. --- ## System Architecture: Coordinator and Worker Threads At the core of the Claude Code Projects multi-agent system lies a two-level separation of duties model: ``` ┌──────────────────────────────┐ │ ПОЛЬЗОВАТЕЛЬ / ТЕХЛИД │ └──────────────┬───────────────┘ │ Постановка общей цели ▼ ┌──────────────────────────────┐ │ КООРДИНАТОР (COORDINATOR) │ │ Основной диалог Project │ └──────────────┬───────────────┘ │ ┌───────────────────────┼───────────────────────┐ │ Делегирование │ Делегирование │ Делегирование ▼ ▼ ▼ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ THREAD 1 │ │ THREAD 2 │ │ THREAD 3 │ │ Облачная сессия │ │ Облачная сессия │ │ Облачная сессия │ │ Ветка: `feat/p75`│ │ Ветка: `ref/api` │ │ Ветка: `fix/db` │ │ Тесты ➔ PR #101 │ │ Тесты ➔ PR #102 │ │ Тесты ➔ PR #103 │ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ │ │ │ └───────────────────────┴───────────────────────┘ │ Общая память: `MEMORY.md` / `CLAUDE.md` ``` ### Comparison Table of System Levels: | Component | Role in the System | Execution Environment | Context and Memory | Primary Output | | :--- | :--- | :--- | :--- | :--- | | **Coordinator** | Control center, dispatcher | Main project dialogue | Sees reports from all threads | Decomposition, consolidated status | | **Thread** | Autonomous worker agent | Cloud session (Cloud VM) | Own copy of the Git branch | Ready Pull Request, tests | | **Subagent** | Highly specialized assistant | Inside a specific Thread | Local processing loop | Micro-script execution | --- ## 1. The Coordinator: Control Center The main conversation within a Project acts as the dispatch node. This is where you direct high-level requirements, technical specifications, and adjustments. The Coordinator performs the following tasks: - **Requirement intake:** analyzes complex requests and defines task boundaries. - **Routing:** decides whether to launch a new thread or pass the task to an existing context. - **Report aggregation:** receives concise summaries from agents without cluttering the main chat with gigabytes of intermediate logs. - **Synthesis:** combines results from disparate threads into a unified final product. > [!IMPORTANT] > The Coordinator does not perform low-level work itself. It acts as a tech lead: distributing roles, validating architectural compatibility, and monitoring execution status. --- ## 2. Worker Threads: Cloud Developers Each **Thread** is a fully independent Claude Code session deployed in cloud infrastructure. When working with the codebase, each thread: - **Isolates the environment:** clones a fresh copy of the repository into a separate container. - **Works in its own branch:** creates a Git branch for a specific feature, avoiding direct conflicts with neighboring agents. - **Validates code:** runs local linters, unit tests, and integration scenarios. - **Finalizes output:** independently opens a Pull Request on GitHub and sends a brief summary to the coordinator. You can continue assigning new tasks to the coordinator while several threads simultaneously refactor different modules of the system. --- ## 3. How Claude Decomposes Tasks You do not need to manually slice tasks or create agents via interface buttons. You send a global requirement to the chat, and the coordinator chooses one of three strategies: ### Strategy A: New Task ➔ New Thread If the task is independent and requires significant changes, the coordinator creates a clean cloud session for it. For example, if you ask in one prompt: - *"Optimize API cold start speed and update documentation in the OpenAPI specification"* — Claude will launch two isolated threads in parallel. ### Strategy B: Topic Development ➔ Existing Thread If new input complements a task the thread is already working on, Claude avoids creating duplicates. It directs the request to the warmed-up context, where the agent remembers previous edits and the structure of affected files. ### Strategy C: Simple Question ➔ Answer in Main Chat Short reference queries (*"What Node.js version is specified in the root package.json?"*) are handled instantly by the coordinator in the main window, without wasting time initializing a cloud container. > [!TIP] > **Coordinator logic control:** if you don't like the automatic distribution, set a strict rule in the chat: > `"Before creating any new threads, always show me the decomposition plan and wait for my confirmation."` --- ## 4. Overview Panel: Transparent Status Control When 5–10 agents are working simultaneously on a project, monitoring them via separate terminals is impossible. All activity is consolidated into the **Overview** dashboard. ### Thread Lifecycle Matrix: | Thread Status | What Happens Under the Hood | User Action Required | | :--- | :--- | :--- | | **`Working`** | The agent is writing code, running builds, or executing tests | No intervention needed; task is in progress | | **`Waiting on you`** | The agent is blocked: action confirmation or an API key is required | Open the thread and provide a response / confirmation | | **`Ready for review`** | Code is written, tests passed, Pull Request opened | Conduct code review in GitHub | | **`Landing`** | Pull Request approved and awaiting merge into the main branch | Confirm the Merge | | **`Idle`** | The agent has finished work and is in standby mode | The thread is ready to accept the next subtask | | **`Resolved`** | Branch merged, task fully closed | The thread is archived | ### Specialized Project Tabs: - **Library:** The project's knowledge base where specifications, reports, and data files created by agents are stored. - **Pull Requests:** A unified list of all PRs opened by agents with CI status indicators. - **Routines:** Scheduled regular procedures (e.g., daily dependency security audits). --- ## 5. Shared Project Memory: Lossless Synchronization All threads within a single project do not operate in isolation — they are connected to a unified **Project Memory** system. ``` Project Root/ ├── MEMORY.md # Main index of decisions, architectural rules, and constraints ├── CLAUDE.md # Local instructions for the specific repository └── docs/ # Specifications and documentation accessible to all agents ``` ### What Claude Remembers: - **Architectural agreements:** e.g., rejecting library X in favor of lightweight solution Y. - **Operational frameworks:** moving release dates, special approval regulations for edits in the billing module. - **Author preferences:** code style conventions, forbidden patterns, package manager choice (`pnpm` instead of `npm`). Every new thread reads the `MEMORY.md` file first upon startup. Therefore, you don't have to repeat basic project requirements to the same agents over and over. --- ## 6. How to Intervene in Individual Agent Work Despite the high level of coordinator autonomy, the developer retains full control over each link. You can "drill down" into any thread at any time: - **View Full Transcript:** A minute-by-minute log of executed shell commands, read files, and linter outputs. - **Targeted Course Correction:** Sending direct instructions to a specific agent (*"Focus only on the /checkout endpoint, leave the rest alone for now"*). - **Emergency Stop:** Interrupting a looping thread with one click. > [!WARNING] > **Critical Routing Rule:** > If an agent stops and requests permission to perform a dangerous action (e.g., deleting files or deploying), you must confirm the command **strictly inside the Thread itself**. A "Continue" command sent to the general coordinator chat will not reach the blocked thread! --- ## 7. Practical Use Cases The multi-agent approach is particularly effective in four engineering scenarios: ### Scenario 1: Performance Optimization (Latency Profiling) **Task:** Reduce checkout service response latency (Checkout p75 latency) from 800 ms to 200 ms. - *Thread 1:* Profiles SQL queries to the database and creates a migration for missing indexes. - *Thread 2:* Configures Redis caching for heavy catalog responses. - *Thread 3:* Optimizes client bundle size and removes unused imports. Each thread prepares a separate PR with isolated benchmarks. ### Scenario 2: Cross-Repository API Migration **Task:** Deprecate the legacy v1 API across all adjacent company services. - Backend API, Web App, and Mobile App repositories are connected to the Project. - The coordinator launches 3 threads: each thread migrates calls to the v2 API in its own repository, runs local tests, and opens a PR specifying the merge order. ### Scenario 3: End-to-End Refactoring Based on Technical Specification **Task:** Implement a complex authorization module according to the `docs/auth-spec.md` file. - The coordinator breaks the specification into logical phases: data model generation ➔ middleware implementation ➔ OAuth integration ➔ writing e2e tests. Knowledge is passed from phase to phase via `MEMORY.md`. ### Scenario 4: Batch Audit of Documentation and Contracts **Task:** Review hundreds of contracts or support tickets. - Threads distribute document batches among themselves, extract key risks, and store structured JSON/Markdown summaries in the shared `Library` storage. --- ## 8. Architecture Limitations and Pitfalls Parallel work significantly reduces development time but requires understanding of technical specifics: 1. **Token Consumption and Plan Limits:** Each active Thread consumes model quota independently. Additionally, the coordinator spends tokens reading long reports. The system has a limit — up to **200 new threads per day** per project. 2. **Merge Conflicts:** Although threads work in different branches, simultaneous editing of common modules or configuration files will inevitably lead to merge conflicts that must be resolved manually. 3. **Cloud Environment Isolation:** Threads run in Anthropic's virtual containers. They do not have direct access to your local databases, device emulators, or internal services behind corporate VPNs. For such tasks, a local Claude Code session is still required. 4. **Context windows:** Despite automatic context compaction (*compaction*), the stream may exhaust the available window during prolonged debugging sessions. In such cases, the coordinator creates a clean successor stream. --- ## Summary: A New Level of Division of Labor Claude Code Projects fundamentally changes the engineer's role in the development process: ``` BEFORE: Human writes code ➔ Human runs tests ➔ Human merges branches NOW: Human sets goal ➔ AI coordinator orchestrates ➔ Agents write code ``` Instead of manually typing commands across dozens of terminal windows, the developer transforms into an **architect and technical director of their own team of autonomous AI agents**, retaining final responsibility for architecture reviews and Pull Request approvals.