Agent Teams Teammate Mode

What Is Teammate Mode, Really?

When you launch Claude Code with the --teammate-mode flag, you're not just enabling a cosmetic feature. You're activating an entire coordination layer that fundamentally changes how Claude sessions interact.

claude-code --teammate-mode

Without this flag, each Claude Code session is isolated. It has its own memory, its own understanding of the project state, and no visibility into what other sessions are doing. When you close the session, that context vanishes (unless you save it manually). It's like working with developers who never read emails. They're all grinding away, but there's no shared reality about what's been done, what's in progress, or what's blocked.

With teammate mode enabled, here's what changes:

1. Shared Context Layer: Sessions write to a shared coordination directory. Every session can read what others have written. This isn't real-time magic—it's file-based coordination. But it works. Files are fast, they're auditable, they persist across session boundaries, and they're already version-controlled by git.

2. Session Identity: Each Claude instance gets a session ID. This ID persists across the session and lets the coordination layer track who did what. No ambiguity about which session completed which task. When you look back at the history, you see clear attribution.

3. Task Assignment Protocol: Teammates can formally assign work to each other. Tasks include descriptions, subtasks, and status tracking. When you assign a task to a teammate, they'll see it when they start their session. They get rich context—requirements, dependencies, related files, even knowledge base links. This prevents the "I didn't know you needed X" problem.

4. Progress Visibility: Instead of wondering if that frontend work is done, you can check the coordination directory and see exactly where teammates are. Not vague status like "working on it"—detailed progress milestones, blockers, and what they're currently focused on.

5. Notification Hooks: When a teammate completes a chunk of work, the system can trigger notifications. This isn't Slack integration—it's structured task completion events that other sessions can subscribe to. You know the moment something's ready for integration testing.

The key insight: teammate mode makes Claude sessions aware of each other. It's asynchronous coordination with eventual consistency. Perfect for splitting work across parallel development streams. You don't need to be in the same Zoom call. Sessions work at their own pace. But when one finishes a major piece, others see it immediately and can adjust priorities.

The Coordination Architecture

Let's get concrete about how this actually works. Teammate mode relies on a simple but elegant coordination structure in your project root. Understanding this structure is critical because you'll be interacting with it directly.

When you enable teammate mode, Claude Code creates (or uses) a .claude/coordination/ directory. This is your team's shared workspace:

.claude/coordination/
├── sessions/
│   ├── session-id-1/
│   │   ├── status.json
│   │   ├── current-task.md
│   │   ├── progress.jsonl
│   │   └── worktree-mapping.json
│   └── session-id-2/
│       ├── status.json
│       ├── current-task.md
│       ├── progress.jsonl
│       └── worktree-mapping.json
├── tasks/
│   ├── assigned-to-session-1.yaml
│   ├── assigned-to-session-2.yaml
│   └── shared-blockers.yaml
├── notifications/
│   ├── ready-for-review.jsonl
│   ├── completed-work.jsonl
│   └── blockers.jsonl
└── team-manifest.yaml

Each session maintains its own folder under sessions/. Inside, you'll find:

• status.json: What this session is currently doing. Updated frequently (every few minutes of work). Includes the session's assigned task, current focus area, language/framework they're using, when they last had activity.
• current-task.md: Full description of the assigned task. Helps new sessions understand context without having to dig through git history.
• progress.jsonl: Line-delimited JSON of task milestones. "Started frontend module", "Completed API integration", "Ready for review". This is the audit trail. Every significant progress event gets appended. You can reconstruct exactly what happened and when.
• worktree-mapping.json: Maps this session to its git worktree. Critical for coordinating merges. Prevents merge conflicts because each session has its own branch.

The tasks/ directory holds formal task assignments. When a task gets assigned to you, you get a YAML file. It looks like this:

id: task-backend-auth-service
assigned-to: session-abc123
assigned-by: session-xyz789
created-at: 2026-03-16T10:30:00Z
due-date: 2026-03-18T17:00:00Z
title: "Implement OAuth2 Service Layer"
description: |
  Build the OAuth2 authentication service with:
  - Token refresh mechanism
  - Scope validation
  - User context extraction
  - Rate limiting (100 req/min per user)
 
subtasks:
  - name: "Token refresh endpoint"
    status: pending
  - name: "Scope validation logic"
    status: pending
  - name: "Rate limiting middleware"
    status: pending
  - name: "Unit tests"
    status: pending
 
dependencies:
  - task-database-schema
  - task-user-model
blocked-by: []
context:
  worktree: feature/oauth2-service
  branch: oauth2-service
  related-files:
    - services/auth/oauth2.ts
    - middleware/rate-limit.ts
  knowledge-base: auth-architecture.md

When this task lands in your session, you see it. You can query it, load the related files, understand the context. Then you work. As you make progress, you update subtask statuses. Other sessions see these updates. The frontend session, waiting on the OAuth2 API, can see that you've completed the token refresh endpoint and start building the client integration against that specific feature.

The notifications/ directory is where asynchronous communication happens. When you complete a major milestone, you append to completed-work.jsonl:

{"timestamp": "2026-03-16T11:45:00Z", "session": "session-abc123", "message": "OAuth2 token refresh endpoint complete and tested", "status": "ready-for-review", "files": ["services/auth/oauth2.ts", "tests/auth.test.ts"]}
{"timestamp": "2026-03-16T12:00:00Z", "session": "session-abc123", "message": "Scope validation logic integrated", "status": "in-progress", "next-milestone": "Rate limiting middleware"}

Other sessions can poll this file. "Hey, is that OAuth work done?" They check notifications/completed-work.jsonl, see the timestamps, and know exactly what's ready. No surprises during integration. No "oops, we built against the wrong API contract."

This architecture is beautifully simple: no central server, no database, no complex coordination protocol. Just structured files in git. It persists. It's auditable. Every session can see the entire history. You can even manually edit files if you need to reassign tasks or update status. It's transparent and human-readable.

Multi-Session Coordination in Practice

Okay, so the structure exists. But how do you actually use it when you're coordinating real work? How does this prevent the chaos that happens when two people are working on the same feature?

Let's walk through a scenario: you're building a full-stack feature. Search functionality with smart caching. You want one Claude session on the backend (database queries, cache invalidation) and another on the frontend (UI, search input handling, results rendering). You're trying to parallelize the work. Backend and frontend can happen in parallel, but they need to stay coordinated around the API contract.

Session 1 (Backend) starts:

claude-code --teammate-mode --worktree backend-search

Claude Code creates a new worktree named backend-search. The session generates a session ID (let's say sess-backend-001) and writes its status to .claude/coordination/sessions/sess-backend-001/status.json:

{
  "session-id": "sess-backend-001",
  "created-at": "2026-03-16T08:00:00Z",
  "status": "active",
  "worktree": "backend-search",
  "branch": "feature/search-backend",
  "assigned-task": "task-search-backend",
  "last-activity": "2026-03-16T08:00:00Z",
  "context": {
    "language": "python",
    "framework": "fastapi",
    "current-focus": "database-query-optimization"
  }
}

Session 2 (Frontend) starts (maybe an hour later):

claude-code --teammate-mode --worktree frontend-search

This creates a different worktree (frontend-search) and a different session ID (sess-frontend-001). When this session starts, it reads the coordination directory and immediately knows:

• Another session is active (backend)
• That session is working on search functionality
• The branch is feature/search-backend
• The focus is database query optimization
• They're using FastAPI, so the API will be REST

The frontend session can pull that context. It knows not to duplicate work. It knows what API contract it needs to build against. It can even read the backend's progress file and see "Database indexing complete, testing query latency now." That tells the frontend session: "The backend is still optimizing. I should probably wait another 30 minutes before writing integration tests."

Now here's the powerful part: you formally assign tasks. Instead of vague Slack messages ("hey can you build the search API?"), you create structured task assignments:

# In the frontend session, you create a task and assign it to backend:
claude-code --assign-task-to sess-backend-001 \
  --task-file services/search/api-contract.yaml \
  --title "Finalize Search API Contract" \
  --due-date 2026-03-16T17:00:00Z \
  --description "Frontend needs stable API by 5pm EOD for integration testing tomorrow"

This creates a task in the coordination layer. The backend session sees it: "Frontend needs the API contract locked down by 5pm. Currently I'm optimizing query performance. That's important, but not as critical as the API contract. Let me reprioritize."

The backend session updates its status:

{
  "session-id": "sess-backend-001",
  "status": "active",
  "current-focus": "finalizing-search-api-contract",
  "blocked-by": [],
  "next-milestone": "API contract stable for frontend integration",
  "priority": "high"
}

Frontend session sees this. Now it knows the backend is focused on finalizing the API. It can start writing the client code based on the API schema, with confidence that it won't change.

Task Assignment and Progress Tracking

Task assignment isn't magical, but it's structured and visible. Let's dig into how it works from both the assigner and assignee perspective. This is where teammate mode really shines.

From the Assigning Session

You've got work that depends on something another session is doing. You need to communicate clearly what you need. Instead of prose in a comment, you create a task:

# Create a task definition
cat > task-frontend-search-integration.yaml << 'EOF'
id: task-frontend-search-integration
assigned-to: session-frontend-001
title: "Build Search Results UI Component"
description: |
  Create the search results component that consumes the backend API.
 
  The backend will expose:
  - GET /api/v1/search?q=<query>&limit=50
  - Response: { results: [{id, title, snippet, score}], elapsed_ms: int }
 
  Requirements:
  - Virtualized list (>1000 results is slow otherwise)
  - Real-time query debouncing (300ms)
  - Highlight matching terms in snippets
  - Show elapsed time for transparency
  - Mobile responsive
  - Accessibility: ARIA labels, keyboard navigation
 
subtasks:
  - name: "Create SearchResults component"
    status: pending
  - name: "Implement result virtualization"
    status: pending
  - name: "Add query debouncing"
    status: pending
  - name: "Style for mobile"
    status: pending
  - name: "Add accessibility features"
    status: pending
  - name: "Unit tests (>80% coverage)"
    status: pending
 
dependencies:
  - task-backend-search-api
blocked-by: []
context:
  framework: "React"
  component-location: "src/components/SearchResults.tsx"
  related-files:
    - src/hooks/useSearch.ts
    - src/styles/search.module.css
  design-spec: "https://figma.com/file/xxx"
  performance-targets:
    - render: "< 100ms"
    - debounce-delay: "300ms"
    - virtualization-threshold: "1000 items"
EOF
 
# Assign it to the frontend session
claude-code --assign-task task-frontend-search-integration.yaml

This task lands in the coordination layer. The frontend session will see it immediately (if it polls) or when it checks for updates. It's rich context, not a vague requirement. The frontend session knows exactly what it needs to build, what the API contract is, what performance targets matter, and where to find the design specs.

From the Assigned Session

The frontend session wakes up, checks for new tasks, and loads its assignments:

# List assigned tasks
claude-code --list-tasks --assigned-to me

Output:

Active Tasks:
1. task-frontend-search-integration (sess-backend-001)
   - Status: NOT STARTED
   - Due: 2026-03-16T17:00:00Z
   - Subtasks: 6 (0 complete)
   - Blockers: none
   - Dependency status: task-backend-search-api IN PROGRESS (50%)

2. task-api-error-handling (sess-backend-001)
   - Status: IN PROGRESS (50%)
   - Due: 2026-03-17T12:00:00Z
   - Subtasks: 3 (1 complete)

The session loads the full task description, understands the dependencies and context, and gets to work. It knows that task-backend-search-api is 50% done, so it can start scaffolding the component structure, but should wait before writing integration tests.

As it progresses, it updates the task status:

# Mark a subtask complete
claude-code --update-subtask task-frontend-search-integration \
  "Create SearchResults component" \
  --status complete
 
# Add progress notes with context
claude-code --add-progress-note task-frontend-search-integration \
  "Component created with basic styling and prop interfaces defined. Now implementing virtualization with react-window."

These updates appear in .claude/coordination/sessions/sess-frontend-001/progress.jsonl. The backend session can see them: "Oh, they've created the component structure. The prop interfaces are defined. We should align on the exact response schema to match those props." This feedback loop happens naturally, without explicit communication.

Notification Patterns: Staying in Sync

Here's the honest truth: teammate mode doesn't have push notifications. It's not webhook-based. But it has something arguably better for asynchronous work: structured completion events that other sessions can efficiently poll.

When you complete a major piece of work, you don't just commit it. You emit a notification:

# In the backend session, after the search API is done
claude-code --emit-notification \
  --type work-ready \
  --title "Search API Complete" \
  --message "Search endpoint fully implemented and tested. Response schema verified against frontend requirements. Ready for frontend integration." \
  --files "services/search/api.py" \
  --status ready-for-integration \
  --metadata '{"api_version": "v1", "endpoint": "/api/v1/search", "performance_p99_ms": 145}'

This appends to .claude/coordination/notifications/completed-work.jsonl:

{
  "timestamp": "2026-03-16T15:30:00Z",
  "session": "sess-backend-001",
  "type": "work-ready",
  "title": "Search API Complete",
  "message": "Search endpoint fully implemented and tested. Response schema verified against frontend requirements. Ready for frontend integration.",
  "files": ["services/search/api.py"],
  "status": "ready-for-integration",
  "metadata": {
    "api_version": "v1",
    "endpoint": "/api/v1/search",
    "performance_p99_ms": 145
  }
}

The frontend session periodically checks this file (maybe every 5 minutes of work). When it does, it sees:

# Frontend session polls for updates
claude-code --check-notifications --since 30m

Output:

Recent Notifications (last 30 minutes):
1. Search API Complete (sess-backend-001)
   - Timestamp: 2026-03-16T15:30:00Z
   - Status: ready-for-integration
   - Files: services/search/api.py
   - Performance: p99 = 145ms
   - Message: Search endpoint fully implemented and tested...

Now the frontend session knows: the API I was waiting for is ready. It can fetch the latest, run integration tests, and get to work. No surprises. No "oops, I wrote the wrong API contract" moments. Coordination happened naturally through structured information.

Blocker notifications work similarly:

# Backend hits an issue
claude-code --emit-notification \
  --type blocker \
  --title "Database Index Missing" \
  --message "Query performance is 10x slower than expected. Need index on search_tokens table. Can't finalize API without this fix." \
  --severity high \
  --assigned-to session-frontend-001 \
  --metadata '{"estimated_fix_time_minutes": 15, "workaround": "Use LIMIT 10 for now"}'

This goes to notifications/blockers.jsonl. The frontend session sees it: "Oh, they need the database schema fixed. That affects my integration tests. Query performance is bad right now. Let me note that dependency and focus on the non-performance-sensitive aspects first. They estimate 15 minutes to fix. I'll check back then."

Practical Setup: Feature Development with Teams

Enough theory. Let's build a real scenario from scratch. This is where teams see the real value.

Scenario: Building a Real-Time Collaboration Feature

Your product needs real-time collaboration—multiple users editing the same document simultaneously. This is complex and requires specialized knowledge across multiple domains:

• Backend: WebSocket server, operational transform engine, conflict resolution, document versioning
• Frontend: React component that syncs with WebSocket, conflict UI indicators, presence awareness
• Infrastructure: Message queue, maybe Redis for session management, monitoring and alerting

You're going to split this across three Claude sessions: backend, frontend, and infrastructure. They'll work in parallel. Infrastructure can start immediately. Backend needs infrastructure groundwork but can proceed mostly independently. Frontend depends on the backend API contract but can scaffold in parallel.

Step 1: Create the Project Structure

# Initialize the project with teammate mode
cd your-project
claude-code --init-teamspace --name "Collaboration Feature"

This creates .claude/coordination/ and sets up the team manifest:

# .claude/coordination/team-manifest.yaml
team-name: "Collaboration Feature"
created-at: 2026-03-16T08:00:00Z
session-count: 0
active-sessions: []
tasks:
  total: 0
  in-progress: 0
  blocked: 0
  complete: 0
notifications:
  unread: 0

Step 2: Define and Assign Work

Before any Claude session starts, you outline the work:

# Define the backend work
cat > .claude/coordination/tasks/task-backend-collab.yaml << 'EOF'
id: task-backend-collab
title: "WebSocket Server + Operational Transform Engine"
description: |
  Build the backend service for real-time collaboration.
 
  Requirements:
  - WebSocket server (handle 100+ concurrent connections)
  - Operational Transform (OT) engine for conflict resolution
  - Document versioning and history
  - User presence tracking (who's online, cursor positions)
  - Message queue integration (Redis pub/sub)
  - Rate limiting and connection management
 
subtasks:
  - name: "WebSocket server with authentication"
    status: pending
  - name: "OT engine core logic"
    status: pending
  - name: "Conflict resolution strategy"
    status: pending
  - name: "Message queue integration"
    status: pending
  - name: "API documentation"
    status: pending
  - name: "Load tests (100+ concurrent)"
    status: pending
 
dependencies: []
blocked-by: []
context:
  language: python
  framework: FastAPI
  worktree: backend-collab
  branch: feature/real-time-collab
EOF
 
# Define the frontend work
cat > .claude/coordination/tasks/task-frontend-collab.yaml << 'EOF'
id: task-frontend-collab
title: "React Component + WebSocket Client"
description: |
  Build the frontend for real-time collaboration.
 
  The backend will expose a WebSocket at wss://api.example.com/ws/collaborate/<doc-id>.
  Messages are JSON: { type, payload, version }.
 
  Requirements:
  - Real-time text editor with conflict indicators
  - User presence (who's editing, cursor positions)
  - Offline mode with sync-on-reconnect
  - Conflict resolution UI (show conflicts, let user resolve)
  - Performance: handle 10,000+ character documents
  - Undo/redo that respects operational transforms
 
subtasks:
  - name: "WebSocket client wrapper"
    status: pending
  - name: "React editor component"
    status: pending
  - name: "Presence indicator widget"
    status: pending
  - name: "Conflict resolution UI"
    status: pending
  - name: "Offline queue implementation"
    status: pending
  - name: "E2E tests with mock server"
    status: pending
 
dependencies:
  - task-backend-collab
blocked-by: []
context:
  language: javascript
  framework: React
  worktree: frontend-collab
  branch: feature/real-time-collab-ui
EOF
 
# Define the infrastructure work
cat > .claude/coordination/tasks/task-infra-collab.yaml << 'EOF'
id: task-infra-collab
title: "Message Queue + Session Management"
description: |
  Set up infrastructure for real-time collaboration.
 
  Requirements:
  - Redis cluster for session state (pub/sub for broadcasts)
  - Message queue (RabbitMQ or AWS SQS) for document sync
  - Monitoring and alerting (connection drops, message lag)
  - Deployment automation (Terraform, Docker Compose)
 
subtasks:
  - name: "Redis cluster setup"
    status: pending
  - name: "Message queue schema design"
    status: pending
  - name: "Monitoring dashboards"
    status: pending
  - name: "Load test setup"
    status: pending
 
dependencies: []
blocked-by: []
context:
  language: terraform
  worktree: infra-collab
  branch: feature/collab-infra
EOF

Step 3: Launch Sessions and Assign Work

# Session 1: Backend work (in terminal 1)
claude-code --teammate-mode --worktree backend-collab --session-name "Backend Lead" &
 
# Wait a moment for initialization
sleep 2
 
# Session 2: Frontend work (in terminal 2)
claude-code --teammate-mode --worktree frontend-collab --session-name "Frontend Lead" &
 
# Wait a moment
sleep 2
 
# Session 3: Infrastructure work (in terminal 3)
claude-code --teammate-mode --worktree infra-collab --session-name "Infrastructure Lead" &

Each session starts, generates a session ID, and writes to the coordination directory. The first thing each session does: check for assigned tasks. They read the task definitions. They load the context. They start working with full visibility into dependencies.

Step 4: Sessions Coordinate

Now things get interesting.

Backend session reads its task, understands the scope, and starts building the WebSocket server. It finishes the basic auth and OT engine (2 hours of work). It emits a notification:

# In backend session
claude-code --emit-notification \
  --type milestone \
  --title "OT Engine Complete" \
  --message "Operational Transform engine tested with conflict scenarios. Basic WebSocket server ready for integration. Message format documented in API spec." \
  --files "services/collab/ot_engine.py" "services/collab/ws_server.py" \
  --metadata '{"test_coverage": 0.95, "conflicts_tested": ["insert-insert", "insert-delete", "delete-delete"]}'

Frontend session periodically checks notifications. It sees the OT engine is done and understands what message format to expect. It reads the API spec. It starts building the React component with confidence: "I know exactly what the backend is sending because it's documented and tested."

Infrastructure session is independent—it can work on Redis setup and monitoring in parallel. No blocking dependencies. It plows ahead and gets infrastructure standing up.

Later, backend needs the infrastructure ready. It emits a blocker:

# In backend session
claude-code --emit-notification \
  --type blocker \
  --title "Redis Setup Needed" \
  --message "Message queue logic ready, but needs Redis connection string and pub/sub topic names. Can't test load scenarios without it." \
  --severity medium \
  --assigned-to infra-collab \
  --metadata '{"required_redis_config": ["REDIS_HOST", "REDIS_PORT", "REDIS_PASSWORD"]}'

Infrastructure session sees this, reprioritizes, and finishes Redis setup earlier than planned. It emits:

# In infrastructure session
claude-code --emit-notification \
  --type work-ready \
  --title "Redis Ready" \
  --message "Redis cluster running locally. Connection string: redis://localhost:6379. Pub/sub topics documented." \
  --files "infra/docker-compose.yml" "infra/redis-config.yaml" \
  --metadata '{"connection_string": "redis://localhost:6379", "pubsub_topics": ["document-updates", "presence-updates"]}'

Backend sees this, picks up the connection string, and proceeds with load testing.

When all three pieces are done, sessions emit "ready-for-integration" notifications:

# Backend
claude-code --emit-notification --type ready-for-integration \
  --title "Backend Complete and Tested"
 
# Frontend
claude-code --emit-notification --type ready-for-integration \
  --title "Frontend Complete and Tested"
 
# Infrastructure
claude-code --emit-notification --type ready-for-integration \
  --title "Infrastructure Deployed"

You check the notifications file, see all three are done, and you merge everything in order: infra → backend → frontend. No merge conflicts because everyone was working in separate worktrees. Clean integration. Feature complete.

Why Teammate Mode Matters

Traditional AI development is "I ask Claude to build the feature, Claude builds it, done." That works for small features. But complex features need distributed cognition. They need specialists.

With teammate mode, you're not limited to one Claude instance wrestling with five different concerns. You have specialists. Each session is deep in its domain. The backend session understands database optimization, API design, and WebSocket protocols. The frontend session understands React performance, accessibility, and UX. The infrastructure session understands deployment, monitoring, and reliability.

They don't step on each other's toes because coordination is explicit. Tasks are formal. Progress is visible. Notifications are structured. Dependencies are tracked. Handoffs are predictable.

This is how teams actually work. We're just extending that pattern to AI development.

When to Use Teammate Mode

Teammate mode isn't for everything. Single-session Claude Code is still great for:

• Small features (refactoring, bug fixes, minor additions)
• Rapid exploration and prototyping
• Solo learning and documentation
• Focused, single-domain problems

Use teammate mode when:

• Your feature spans multiple domains (frontend + backend + infrastructure)
• You're working on a complex system where different parts need deep focus
• You want to parallelize work (two sessions working simultaneously)
• Coordination overhead is worth the efficiency gains (usually features >3 days of work)
• You want auditable task tracking and progress visibility
• You need clear API contracts between different parts of the system
• Team handoffs are critical (you want to avoid rework and misunderstandings)

The break-even point is roughly 3+ days of complex work or 3+ distinct problem domains. For smaller projects, the coordination overhead isn't worth it.

Deep Dive: Handling Merge Conflicts in Team Scenarios

When you're running multiple sessions in parallel, merge conflicts are a real concern. However, teammate mode is specifically designed to minimize them. Let me show you how the architecture prevents conflicts and what to do when they occur.

The fundamental principle is separation of concerns. Each session works in its own git worktree, which means each session has its own branch. Two sessions editing the exact same file in conflicting ways is extremely rare because they're typically working on different files or different parts of the system.

But here's where it gets interesting: what happens when two sessions legitimately need to edit the same file? Say both the backend and frontend sessions need to update a shared types file. How do you coordinate that without conflicts?

Answer: Task dependencies and notification patterns.

Before the frontend session modifies the shared types file, it checks if that file is in another session's "related files" list. If it is, the frontend session emits a notification: "About to modify types.ts. Backend session, please review." The backend session sees this notification, finishes its work on types.ts, commits it, and notifies the frontend. The frontend session then proceeds with its changes.

This is human-like coordination but implemented through structured files. There's no real-time coordination. But the notification pattern creates a natural ordering that prevents conflicts.

In practice, here's how you handle potential conflicts:

# Before modifying a shared file, check who else might be using it
claude-code --check-file-locks "src/types.ts"
 
# Output might be:
# This file is related to: task-backend-api (sess-backend-001)
# Last modified by: sess-backend-001 at 2026-03-16T14:30:00Z
# Current status: Complete, committed to feature/search-backend
 
# Safe to modify. Emit a notification first.
claude-code --emit-notification \
  --type file-modification \
  --title "About to modify src/types.ts" \
  --message "Frontend session modifying types for SearchResult interface" \
  --files "src/types.ts"
 
# Do your work
# ...commit...
 
# Notify others that you're done
claude-code --emit-notification \
  --type work-ready \
  --title "SearchResult types finalized" \
  --message "Types updated in src/types.ts. Ready for backend integration."

If a conflict does occur during merge, it's usually because notifications weren't checked. When merging sessions:

# Merge in dependency order, and be explicit about conflicts
git checkout main
git merge backend-feature
 
# If conflict occurs in shared file:
git status  # Shows conflicts
# Edit the conflicting file(s) to resolve
git add resolved-file.ts
git commit -m "Resolve conflict: merged backend types with frontend interface definitions"
 
# Then merge frontend
git merge frontend-feature

The key is that worktrees prevent 99% of conflicts automatically. The remaining 1% are handled by coordination through notifications.

Understanding Session Lifecycle and Cleanup

Sessions have lifecycles. They're created, they do work, they complete, and then they need to be cleaned up. Understanding this lifecycle is critical for maintaining a healthy team coordination system.

Session States:

• pending: Session is initialized but hasn't started work yet
• active: Session is currently doing work
• paused: Session is waiting (blocked on a dependency)
• completed: Session has finished its work
• abandoned: Session was started but stopped without completion

When a session moves to "abandoned", it can cause problems. Its tasks remain assigned. Other sessions might be waiting on work that will never arrive. That's why periodic cleanup is essential.

# List all sessions and their states
claude-code --list-sessions --all
 
# Example output:
# sess-backend-001 (active, 4 hours old, last activity 5 min ago)
# sess-frontend-001 (active, 3 hours old, last activity 12 min ago)
# sess-infra-001 (completed, 2 hours old, finished 30 min ago)
# sess-old-feature-001 (abandoned, 1 week old, no activity for 6 days)
 
# Clean up abandoned sessions
claude-code --cleanup-sessions --inactive-for 6h
 
# Or force cleanup if you know a session is done
claude-code --mark-session-complete sess-infra-001

When a session is marked complete, its tasks are considered delivered. If downstream sessions are waiting on it, they check for notifications to understand what was completed. The completed session's coordination files remain in git history for auditing.

Deep Dive: Context Synchronization Across Sessions

One subtle but important aspect of team coordination is context synchronization. All sessions need to agree on the same understanding of the project. But they're independent—how do they stay synchronized?

The answer is periodic context refresh. Each session, when it wakes up or checks for updates, reads the latest task descriptions, notifications, and progress files. This is like reading the latest Slack messages—you might not have everything, but you know what's happened recently.

Here's what happens behind the scenes when a session starts:

session_startup_flow:
  1_initialize:
    - generate_session_id
    - read_team_manifest
    - check_coordination_directory_timestamp
 
  2_discover_context:
    - scan_tasks_directory
    - load_assigned_tasks
    - scan_notifications_directory
    - fetch_recent_notifications (last 24 hours)
 
  3_read_teammates_status:
    - list_active_sessions
    - load_each_session's_status.json
    - understand_dependencies
    - identify_blockers
 
  4_sync_project_state:
    - run_git_pull_to_sync_latest
    - verify_worktree_branches_exist
    - check_if_dependencies_are_ready
 
  5_determine_readiness:
    - if_blocked_by_dependency: enter_paused_state
    - if_all_ready: enter_active_state
    - if_no_assigned_task: wait_for_assignment

This happens in the first 30 seconds of session startup. By the time the session's ready to accept commands, it has a complete picture of who's doing what, what depends on what, and where the blockers are.

Practical Tips and Gotchas

Tip 1: Worktrees Are Your Friend

Always use worktrees with teammate mode:

claude-code --teammate-mode --worktree my-feature-name

This ensures each session gets its own git branch. No merge conflicts. Clean, isolated work. When the feature is done, you merge the worktree branch into main. This is non-negotiable for team coordination.

Tip 2: Over-Communicate in Task Descriptions

The task description is your async communication. Make it rich:

# Good
title: "Build Search API"
description: "Add search endpoint"
 
# Better
title: "Build Search API"
description: |
  Create GET /api/v1/search?q=<query>&limit=50
 
  Response format:
  {
    "results": [
      {
        "id": "string",
        "title": "string",
        "snippet": "string (first 150 chars)",
        "relevance_score": "float 0-1"
      }
    ],
    "elapsed_ms": "int"
  }
 
  Implementation notes:
  - Use PostgreSQL full-text search
  - Results sorted by relevance_score DESC
  - Limit max results to 1000 for performance
  - Cache queries for 1 hour (Redis)
  - Rate limit: 100 req/min per user
 
  Testing:
  - Test with >100k documents
  - Benchmark: <500ms response for typical queries
  - Test edge cases: empty query, special characters, unicode
 
  Performance targets:
  - p50: <100ms
  - p95: <300ms
  - p99: <500ms

Over-communication prevents rework. Every question the assigned session might ask, answer in advance.

Tip 3: Emit Notifications Liberally

Don't wait for major milestones. Notify teammates when:

• You complete a subtask (even small ones)
• You hit a blocker or discover a constraint
• You're changing an API contract or design decision
• You need feedback on design choices
• You discover something that affects them (e.g., "performance will be lower than expected")

# Small notifications are fine
claude-code --emit-notification \
  --type progress \
  --title "API auth strategy decided" \
  --message "Using JWT with 1-hour expiry. Refresh token stored in secure cookie. Ready for frontend integration."
 
# Blockers are critical
claude-code --emit-notification \
  --type blocker \
  --title "Database performance issue" \
  --message "Search queries taking 5+ seconds. Need index on created_at column. Can't proceed with integration testing until this is fixed."
 
# Design decisions that affect others
claude-code --emit-notification \
  --type design-decision \
  --title "Caching strategy finalized" \
  --message "Using Redis with 1-hour TTL. Invalidation on content change. This affects how you call the API."

More notifications = better coordination. It's cheap to send, and it prevents surprises.

Tip 4: Merge in the Right Order

If there are dependencies, merge in order:

# Infrastructure first (no dependencies)
git checkout main
git merge infra-collab
git push
 
# Backend next (depends on infrastructure)
git merge backend-collab
git push
 
# Frontend last (depends on backend)
git merge frontend-collab
git push

This ensures each session's work is compatible. If you merge frontend first, it might break when backend is merged.

Gotcha 1: Notification Files Grow

Notification files are append-only. They'll grow over time (hundreds of lines per day on an active team). Periodically archive old ones:

# Archive notifications older than 30 days
claude-code --archive-notifications --older-than 30d --target .claude/archives/

This keeps the working directory fast and focused.

Gotcha 2: Stale Task Assignments

If a teammate session crashes or is abandoned, tasks stay assigned. Periodically clean up:

# List inactive sessions (no activity for >6 hours)
claude-code --list-sessions --inactive-for 6h
 
# Reassign their tasks
claude-code --reassign-tasks --from inactive-session --to active-session

Don't let tasks languish. Reassign them so work keeps moving.

Gotcha 3: Context Drift

Each session has its own mental model. After a few hours, they can drift apart on assumptions. Mitigate by:

• Updating task descriptions when scope changes (sessions will re-read)
• Emitting notifications when assumptions change
• Running integration tests frequently to catch mismatches early
• Having sessions re-read the task file periodically to stay synchronized

Setting Up Your First Team

Here's a minimal playbook to get started:

# 1. Initialize teamspace
cd your-project
claude-code --init-teamspace --name "Feature Name"
 
# 2. Define tasks (in YAML, like examples above)
# Create .claude/coordination/tasks/*.yaml for each workstream
 
# 3. Launch sessions (in separate terminals)
claude-code --teammate-mode --worktree backend-feature --session-name "Backend" &
claude-code --teammate-mode --worktree frontend-feature --session-name "Frontend" &
 
# 4. Let each session load its tasks and context
# Sessions will automatically see coordination files
# They'll start making progress
 
# 5. Check progress periodically
claude-code --list-tasks --status all
claude-code --check-notifications --since 1h
 
# 6. Merge when complete (per dependency order)
git checkout main
git merge backend-feature
git merge frontend-feature

That's it. Three commands to launch a coordinated team. The coordination layer handles the rest.

Avoiding Common Mistakes

Mistake 1: Too Many Sessions

Three sessions is okay. Ten is chaos. Each session adds coordination overhead. Keep it to the minimum needed to parallelize the work.

Mistake 2: Unclear Task Ownership

Make it obvious who owns what. If two sessions are both working on the same API, someone will get confused and create duplicate work.

Mistake 3: Ignoring Blockers

When a session emits a blocker, treat it seriously. Don't deprioritize. Blockers block other work. Fix them fast.

Mistake 4: Not Checking Notifications

Sessions should check for notifications every 30 minutes or so. Build it into the workflow. "Before I commit, let me check what else changed."

The Future of AI Development

Teammate mode is a preview of how AI-assisted development will scale. Instead of one AI system trying to understand and build everything, we'll have specialized sessions coordinating work.

You might have:

• A security audit session running in parallel, checking every commit
• An optimization session refactoring hot paths
• A test session writing tests as features ship
• A documentation session keeping docs in sync

All coordinated through the same mechanism: shared tasks, progress tracking, notifications. This mirrors how elite engineering teams work. Specialists coordinate through clear communication, visible progress, and structured hand-offs. We're automating that for AI development.

Summary

Claude Code's teammate mode enables true distributed development:

• Multi-session coordination through a shared context layer (no central server needed)
• Task assignment and progress tracking so teammates stay aligned
• Notification patterns for async communication without real-time dependencies
• Practical workflow for splitting complex features across parallel work streams
• Clean merging when work is complete (no conflicts because each session has its own branch)

When you're building something complex, teammate mode turns Claude Code from a single developer into a coordinated team. Each session goes deep on its problem. Coordination happens naturally through structured files. Integration is clean.

Try it on your next feature that spans multiple domains. Launch a backend session and a frontend session. Assign them tasks. Watch them coordinate. Check the notifications file periodically.

You'll realize: this is how AI development should scale.

-iNet