# How to Configure and Coordinate Claude Code Subagents in Shared Workspaces

Claude Code subagents execute scoped tasks in isolated contexts to keep main conversation histories clean. When multiple subagents run in parallel, coordinating their file writes and deliverables requires a shared workspace layer. This guide covers how to define custom subagents in `.claude/agents/`, bind them to Fast.io workspaces via MCP, and prevent merge collisions during multi-agent handoffs.

Source: https://fast.io/resources/claude-code-subagents-agent-rooms/
Last reviewed: 2026-09-04

## Why Multi-Agent Workflows Require Shared Context and Artifact Storage

When multiple Claude Code subagents run concurrently in a local terminal, they operate without awareness of shared files or external deliverables. Without a shared workspace layer, subagents overwrite each other's changes, exhaust local disk boundaries, and leave human supervisors with no visibility into intermediate artifacts.

Standard command line coding sessions degrade over time when complex tasks require deep codebase exploration. A developer investigating a distributed system might prompt an assistant to search repository histories, inspect database schemas, run test suites, and analyze dependency trees. In a conventional monolithic session, every file read, grep snippet, and compiler log gets appended to the primary conversation history. Within an hour, this token accumulation pushes the context window toward capacity, degrading the model's ability to retain earlier architectural guidelines or follow strict constraints.

To resolve this degradation, Claude Code introduces a modular execution pattern. Claude Code subagents are specialized autonomous worker agents spawned by Claude Code to execute scoped tasks concurrently in isolated contexts. Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When a subagent finishes its assignment, it returns a concise summary back to the parent session. The intermediate search output, linting errors, and raw file dumps remain confined to the subagent's temporary context, preserving the main thread for high-level decision making.

However, delegating work to subagents creates a new operational challenge: artifact coordination. Most technical tutorials demonstrate subagents running purely local commands, such as searching a directory or running a unit test in an isolated terminal. In real engineering environments, development involves shared artifacts that extend far beyond simple terminal outputs.

Teams encounter three critical bottlenecks when running local subagents without a shared workspace layer:

1. Direct code overwrites: If two subagents attempt to modify the same repository files concurrently, they overwrite each other's edits, creating unmergeable git conflicts and broken builds.
2. Artifact stranding: Subagents frequently generate valuable non-code deliverables, including architectural decision records, benchmark spreadsheets, database migration scripts, and structured research briefs. When saved only to local temporary directories or scratch disks, these assets remain stranded on an individual developer's machine, inaccessible to teammates or peer agents running in other environments.
3. Version control pollution: Git repositories are engineered to track line-based text diffs across code files, not to manage rapidly changing binary assets, intermediate data dumps, or multi-gigabyte research collections produced by autonomous agent pipelines.

Solving these problems requires a dual-track architecture. Source code modifications must be isolated using branch-level sandboxing like git worktrees, while project assets, reference documents, and agent deliverables must be organized inside a persistent, versioned workspace accessible by humans and agents alike.

## How to Configure Claude Code Subagents in the Agents Directory

Claude Code discovers subagents through Markdown files containing YAML frontmatter. These definitions configure the subagent's identity, prompt instructions, tool permissions, and model parameters. Claude Code scans two primary locations for subagent files:

* Project scope (`.claude/agents/`): Definitions placed in this directory apply specifically to the current repository. Checking this folder into version control ensures that every team member and automated pipeline shares the same worker configurations.
* User scope (`~/.claude/agents/`): Definitions placed in your home directory are globally available across every project on your local workstation, making them suitable for personal utility workers such as documentation formatters or personal security scanners.

When definitions share the same identifier, the project-level file takes precedence over the user-level file, allowing teams to override global defaults with project-specific rules.

The YAML frontmatter supports several configuration keys that dictate how the subagent executes:

* `name`: A unique identifier using lowercase letters and hyphens (for example, `workspace-researcher`).
* `description`: A clear, detailed statement describing what the agent does and when Claude should delegate work to it. Claude matches incoming tasks against this description to decide delegation.
* `tools` and `disallowedTools`: Explicit allowlists or denylists specifying which tools the worker can invoke. For instance, setting `tools: Read, Grep, Glob, Bash` restricts the subagent to reading files and running shell commands while preventing direct write operations to the active repository.
* `model`: Specifies the underlying language model, such as `sonnet`, `haiku`, `opus`, or `inherit`. Routing lightweight discovery tasks to `haiku` reduces inference costs, while complex reasoning tasks can be assigned to `sonnet` or `opus`.
* `permissionMode`: Controls execution security, accepting values such as `default` (prompts for confirmation), `acceptEdits` (auto-approves file modifications), `auto` (evaluates actions with a safety classifier), or `plan` (enforces read-only exploration).
* `isolation`: When set to `worktree`, Claude Code automatically provisions a temporary git worktree branched from the default branch, preventing the subagent from altering the user's active checkout.
* `mcpServers`: Declares external Model Context Protocol connections scoped exclusively to this subagent.

### Step-by-Step Subagent Configuration

To define a custom subagent and connect it to a shared cloud workspace, follow these seven steps:

1. Create the project agents folder: In your repository root, create the directory `.claude/agents/` if it does not already exist.
2. Create the definition file: Add a markdown file named `.claude/agents/workspace-researcher.md`.
3. Set name and delegation description: Add YAML frontmatter defining `name: workspace-researcher` and write a descriptive `description` detailing the specific research scenarios where this agent should be invoked.
4. Restrict tool access: Add `tools: Read, Grep, Glob, Bash` to prevent the subagent from overwriting local project files during research.
5. Enable worktree sandboxing: Include `isolation: worktree` to ensure any local git operations run in an isolated working tree rather than modifying your active branch.
6. Declare the shared workspace MCP endpoint: Add an inline `mcpServers` block pointing to the remote Fast.io MCP server at `https://mcp.fast.io/mcp/key`, passing your API key header.
7. Author the system prompt: Below the frontmatter fence, write instructions detailing how the agent queries workspace intelligence, analyzes documents, and writes deliverables into designated project folders.

Here is a complete subagent definition implementing this pattern:

```markdown
---
name: workspace-researcher
description: Conducts deep document research and compiles structured project briefs. Use when analyzing specifications or cross-referencing workspace assets.
tools: Read, Grep, Glob, Bash
model: sonnet
isolation: worktree
mcpServers:
  - fastio-workspace:
      type: http
      url: https://mcp.fast.io/mcp/key
      headers:
        Authorization: "Bearer YOUR_FASTIO_API_KEY"
---

You are a specialized research subagent. Your job is to analyze project documentation, extract key requirements, and save structured summaries.

When assigned a research task:
1. Use the Fast.io MCP search tools to locate relevant reference documents in the shared workspace.
2. Read the source documents and extract architectural constraints, data schemas, and interface definitions.
3. Synthesize your findings into a comprehensive markdown brief.
4. Upload the completed brief directly to the workspace under `/staging/research/` using the Fast.io MCP upload tool.
5. Return a concise executive summary to the primary session with the path of the uploaded file.
```

Scoping MCP connections directly inside the subagent frontmatter provides a major context optimization. When MCP servers are declared in the global `.mcp.json` file, their tool schemas are loaded into the primary conversation at startup, consuming thousands of tokens before any work begins. Defining the server inline within the subagent frontmatter ensures that the workspace tools load only when that specific worker is active, keeping the parent thread uncluttered.

## Connecting Subagents to Shared Workspaces via Remote MCP

When multiple subagents collaborate on a project, local storage creates immediate coordination friction. If a research subagent generates an architecture brief on a developer's local laptop, a backend subagent running in a separate session cannot read it. Attempting to bridge this gap with consumer cloud storage services like Google Drive or Dropbox introduces severe operational issues. Those platforms rely on background desktop synchronization clients that lock files unpredictably, throttle API requests during rapid writes, and lack native Model Context Protocol support.

Fast.io serves as an intelligent workspace platform built specifically for agentic teams. Rather than treating storage as a passive bit repository, Fast.io provides a collaborative environment where both software engineers and autonomous AI agents interact with the same underlying file system. When an agent or human adds a file to a Fast.io workspace, the platform's Intelligence Mode indexes the content for semantic meaning-based search and full-text retrieval.

The Fast.io MCP server is remote, operating over Streamable HTTP at `https://mcp.fast.io/mcp/key` with a legacy SSE transport option at `https://mcp.fast.io/sse`. Because it runs remotely, developers do not need to install local npm packages or manage local daemon processes. Client configurations connect directly to the hosted endpoint using a scoped API key.

To connect your Claude Code environment to a shared workspace across all sessions, add the server to your project's `.mcp.json` file:

```json
{
  "mcpServers": {
    "fastio": {
      "type": "http",
      "url": "https://mcp.fast.io/mcp/key",
      "headers": {
        "Authorization": "Bearer YOUR_FASTIO_API_KEY"
      }
    }
  }
}
```

Once connected, subagents can execute three core workspace workflows:

First, subagents retrieve project context through hybrid search. Instead of requiring developers to manually copy reference specifications into local folders, subagents call the workspace search endpoint (`GET /current/workspace/{workspace_id}/storage/search/`). This unified search combines exact text matching with semantic retrieval, returning relevant file passages along with document citations.

Second, subagents persist intermediate deliverables directly to the cloud. When a testing subagent generates benchmark logs, or a documentation subagent generates API references, it writes the files directly into designated workspace folders. These files are instantly accessible to peer agents running on other machines or to human teammates reviewing progress in the browser UI. For detailed endpoint capabilities, developers can consult the [Fast.io agent storage guide](/storage-for-agents/).

Third, subagents interact with structured document extraction through [Metadata Views](/product/document-data-extraction/). Metadata Views turn unstructured PDFs, Word documents, spreadsheets, and scanned records into typed, queryable databases. When teams configure a Metadata View, the platform extracts structured fields such as vendor names, contract dates, line-item totals, and technical specifications into typed columns (Text, Integer, Decimal, Boolean, URL, JSON, Date & Time). Subagents can query these structured views programmatically through MCP, retrieving precise data points across hundreds of project files without parsing raw document text repeatedly.

By centralizing project data in a shared workspace, subagents avoid duplicating token-intensive context reads. When onboarding new agents to an established project, teams can point them directly to the workspace index using the [agent onboarding guidelines](https://fast.io/llms.txt) to ground their tasks in verified project knowledge.

## How to Prevent Merge Collisions with Worktrees and Versioned Storage

Running concurrent subagents introduces concurrency hazards. When two agents work in parallel on the same repository, uncoordinated file writes inevitably lead to dirty working directories, overwrites, and corrupt test runs.

To eliminate these conflicts, engineering teams must separate code modifications from data artifacts:

* Source code is managed through git worktrees.
* Research assets, intermediate outputs, and test logs are managed through Fast.io workspaces.

In Claude Code, setting `isolation: worktree` in a subagent's frontmatter instructs the CLI to isolate that worker. When spawned, the subagent does not touch your active working directory. Instead, Claude Code creates a clean git worktree in a temporary directory branched from your repository's default branch. The subagent executes all file edits, script executions, and linting checks within that sandboxed tree. If the subagent completes its task successfully, the changes can be committed to a dedicated feature branch or reviewed as a patch. If the subagent encounters errors or makes no changes, the worktree is cleaned up without leaving uncommitted remnants in your primary workspace.

While git worktrees protect the codebase, they do not solve artifact persistence. Committing generated test logs, dataset exports, or research PDFs to a git repository creates bloat and triggers git lock contention when multiple branches merge.

Fast.io resolves artifact concurrency by maintaining an automatic per-file version history on every uploaded asset. When a subagent writes an updated report or dataset to an existing path in the workspace, Fast.io does not destructively overwrite the previous content. Instead, it creates a new version while preserving the complete historical timeline.

This per-file versioning provides three critical safeguards:

1. Rollback protection: If an agent writes an incomplete or corrupted dataset, human supervisors or peer agents can inspect prior versions and restore an earlier state through the UI or API.
2. Concurrent write auditing: When two subagents output to the same directory structure, each revision is tracked with distinct timestamps and actor identities, preventing silent data loss.
3. Zero-downtime handoffs: Downstream agents and human reviewers always access the latest verified version of an asset, while maintaining the ability to trace the full evolution of the document.

Rather than relying on polling loops to detect when an agent finishes an upload, applications and peer agents can track workspace changes using Fast.io's activity polling endpoint (`GET /current/activity/poll/{entity_id}?wait=95&lastactivity={timestamp}`) or subscribe to the WebSocket live events feed. When an agent uploads a completed deliverable, the activity feed broadcasts the event, allowing downstream processes to react immediately.

To maximize coordination efficiency, teams should adopt a standardized directory hierarchy within the shared workspace:

```text
/project-alpha/
├── specifications/
│   ├── api-contracts.json
│   └── requirements.md
├── staging/
│   ├── subagent-research/
│   └── subagent-testing/
├── extracted-data/
│   └── schema-views.csv
└── deliverables/
    ├── architecture-brief.pdf
    └── release-notes.md
```

Under this structure, input specifications remain read-only for subagents, staging folders provide isolated write zones for parallel workers, and the deliverables folder serves as the staging ground for human review.

## Supervising Multi-Agent Workflows and Handing Off to Humans

As development teams increase the number of subagents operating across codebases, human supervision becomes the primary determinant of system reliability. Autonomous execution without structured visibility risks shipping unverified code or making decisions that violate project policies.

Fast.io bridges the gap between autonomous agent execution and human oversight through three core capabilities: immutable audit logging, live multiplayer collaboration, and ownership transfer.

Every action performed within a Fast.io workspace is permanently captured in an append-only audit log. When an agent creates a folder, updates a specification, queries an indexed document, or shares an asset, the platform appends an immutable event record. The log captures the exact timestamp, actor identity, operation type, and affected file path. Because the audit log cannot be modified or truncated by agents, engineering managers maintain a verifiable chain of custody for all automated activities, ensuring compliance with organizational governance standards.

For collaborative oversight, teams use Fast.io Notes. Fastio Notes brings real-time co-editing to every workspace, complete with visible multiplayer cursors where both human engineers and AI agents collaborate as first-class editors on the same document. A human lead can draft high-level requirements in a Note, observe an agent drafting API specifications in real time, and adjust phrasing inline. Because Notes are indexed into the workspace intelligence layer, any guidance added by a human supervisor becomes searchable context for subsequent agent runs.

When agents build out complete project environments, Fast.io enables ownership transfer. An agent can use a scoped API key to sign up, configure an organization, provision workspaces, organize project folders, and upload initial assets. Once setup is complete, the agent generates an ownership transfer claim link. The human supervisor claims the organization, enters credit card details to start the subscription or trial, and assumes full organizational ownership. The agent retains administrative access to continue daily coding and maintenance tasks, while billing, governance, and organizational control remain securely with the human team.

To maintain reliability when deploying Claude Code subagents with shared workspaces, review this operational checklist:

* Isolate git operations: Ensure all code-modifying subagents declare `isolation: worktree` in their frontmatter to prevent working directory conflicts.
* Confine MCP tool scopes: Define remote workspace MCP servers inline inside `.claude/agents/*.md` definitions to keep tool definitions from consuming tokens in the main session context.
* Centralize non-code deliverables: Route all research briefs, datasets, and generated documentation to designated workspace folders rather than local scratch paths.
* Verify file revisions: Use Fast.io per-file version history to inspect changes and preserve historical drafts across automated iterations.
* Monitor workspace activity: Track file updates and team events using the real-time activity feed to coordinate handoffs between parallel agents.
* Complete ownership handoff: Use ownership transfer claim links so that human managers maintain legal and administrative ownership of agent-created workspaces.

## Frequently asked questions

### What are Claude Code subagents?

Claude Code subagents are specialized autonomous worker agents spawned by Claude Code to execute scoped tasks concurrently in isolated contexts. Each subagent maintains its own context window, custom system prompt, and scoped tool access, allowing it to perform tasks like code review, test execution, or codebase research without crowding the primary conversation history.

### How do you configure custom subagents in Claude Code?

You configure custom subagents by creating Markdown files with YAML frontmatter in `.claude/agents/` (for project-level scope) or `~/.claude/agents/` (for user-level global scope). The frontmatter specifies the subagent's name, delegation description, allowed tools, model tier, permission mode, worktree isolation, and inline MCP servers, while the markdown body provides the specialized system prompt.

### How do multiple Claude Code subagents share files without merge conflicts?

Subagents avoid merge conflicts by separating source code edits from artifact storage. Source code modifications run in temporary git worktrees configured via `isolation: worktree`, preventing concurrent branch overwrites. Shared deliverables, research briefs, and datasets are uploaded to Fast.io workspaces via MCP, where per-file version history preserves all revisions without overwriting teammate assets.

### How does scoping MCP servers inside subagent frontmatter conserve tokens?

When MCP servers are defined in the global `.mcp.json` file, their tool schemas load into the primary conversation context at session startup. Defining an MCP server inline within a subagent's frontmatter under `mcpServers` ensures that the server tools load only into that subagent's independent context window when invoked, keeping the main conversation context clean.

### How do human supervisors audit subagent changes in Fast.io?

Human supervisors audit subagent changes through Fast.io's append-only audit log and per-file version history. The audit log records an immutable timeline of all file operations, access events, and memberships, while version history allows supervisors to inspect prior document iterations and roll back unintended modifications.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.