vault backup: 2026-04-17 13:02:46
This commit is contained in:
Vadym Samoilenko
parent
771c4688a9
commit
4c67539fde
6 changed files with 190 additions and 1 deletions
|
|
@ -23,6 +23,10 @@ created: 2026-04-17
|
|||
- **Local path:** `/Volumes/SSD/Projects/Oliver/Barclays-banner-builder`
|
||||
|
||||
## Sessions
|
||||
### 2026-04-17 – Create a deployment script for Ubuntu
|
||||
**Asked:** Create a deployment script for Ubuntu server with Docker containers, database initialization, and migrations.
|
||||
**Done:** Analyzed application requirements and established deployment strategy with idempotent script for Docker builds, database setup, and frontend file management.
|
||||
|
||||
### 2026-04-17 – Create an idempotent deployment script for
|
||||
**Asked:** Create an idempotent deployment script for Ubuntu server with Docker, database initialization, and migrations.
|
||||
**Done:** Verified login page is functional at optical-dev.oliver.solutions with working authentication flow.
|
||||
|
|
@ -159,6 +163,7 @@ created: 2026-04-17
|
|||
## Change Log
|
||||
| Date | Requested | Changed | Files |
|
||||
|------|-----------|---------|-------|
|
||||
| 2026-04-17 | Deployment script | Docker build with cache, DB initialization, Alembic migrations, frontend cleanup | deploy.sh, docker-compose.yml |
|
||||
| 2026-04-17 | Deployment automation | Docker build caching, database migrations, idempotent script logic | deploy.sh, docker-compose.yml |
|
||||
| 2026-04-17 | Deployment script | Docker build with cache refresh, database initialization and migrations, Apache Include configuration | deploy-ubuntu.sh, apache-barclays.conf, sites-enabled/optical-dev.oliver.solutions.conf |
|
||||
| 2026-04-17 | Deployment script & Apache config | Fixed sites-enabled patching, updated deploy.sh for correct config file | deploy.sh, apache-config-patch |
|
||||
|
|
|
|||
|
|
@ -224,3 +224,9 @@ tags: [daily]
|
|||
- 13:00 | `Barclays-banner-builder`
|
||||
- **Asked:** Create an idempotent deployment script for Ubuntu server with Docker, database initialization, and migrations.
|
||||
- **Done:** Verified login page is functional at optical-dev.oliver.solutions with working authentication flow.
|
||||
- 13:01 (<1min) | `Barclays-banner-builder`
|
||||
- **Asked:** Create a deployment script for Ubuntu server with Docker containers, database initialization, and migrations.
|
||||
- **Done:** Analyzed application requirements and established deployment strategy with idempotent script for Docker builds, database setup, and frontend file management.
|
||||
- 13:01 | `memory-compiler`
|
||||
- **Asked:** Asked the developer to compile a raw article into the knowledge base as a structured wiki entry.
|
||||
- **Done:** Compiled and filed the article as `wiki/agent-sdk/observability-opentelemetry.md` with index updates.
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ This 3-hop pattern works for hundreds of articles without vector search.
|
|||
| [[wiki/web-agency/_index\|web-agency/]] | AI-assisted website building & selling: Claude Code, Nanobanana 2, Kling, LaunchPath MCP | 1 |
|
||||
| [[wiki/dotfiles/_index\|dotfiles/]] | Linux terminal ricing: Kitty, Fish, WezTerm CLI, modern Rust CLI tools, LazyVim, unified themes, Tabby | 16 |
|
||||
|
||||
| [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 16 |
|
||||
| [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 17 |
|
||||
| [[wiki/llm-models/_index\|llm-models/]] | OpenAI model catalog — GPT-5.x, o-series reasoning, audio/realtime, embeddings, moderation | 1 |
|
||||
| [[wiki/claude-code/_index\|claude-code/]] | Claude Code product docs — install, capabilities, surfaces, MCP, hooks, scheduling, multi-agent, plugins, skills, error recovery | 7 |
|
||||
|
||||
|
|
|
|||
|
|
@ -21,3 +21,4 @@ Claude Code is Anthropic's agentic coding assistant. Works across terminal, IDE,
|
|||
| [[wiki/claude-code/plugin-marketplaces\|plugin-marketplaces]] | Discover and install plugins: official marketplace, code intelligence (LSP), MCP integrations, scopes, team config, auto-updates, troubleshooting | raw/Discover and install prebuilt plugins through marketplaces.md | 2026-04-17 |
|
||||
| [[wiki/claude-code/error-reference\|error-reference]] | Runtime error lookup: server errors, usage limits, auth, network, request errors, quality checks — with fix commands for each | raw/Error reference.md | 2026-04-17 |
|
||||
| [[wiki/claude-code/skills\|skills]] | Skills system: creation, storage scopes, frontmatter fields, invocation control, dynamic shell injection, subagent execution, bundled skills, sharing | raw/Extend Claude with skills.md | 2026-04-17 |
|
||||
| [[wiki/claude-code/agent-teams\|agent-teams]] | Experimental multi-session teams: lead + teammates, shared task list, direct messaging, hooks, display modes, best practices, limitations | raw/Orchestrate teams of Claude Code sessions.md | 2026-04-17 |
|
||||
|
|
|
|||
177
wiki/claude-code/agent-teams.md
Normal file
177
wiki/claude-code/agent-teams.md
Normal file
|
|
@ -0,0 +1,177 @@
|
|||
---
|
||||
title: "Agent Teams — Orchestrate Multiple Claude Code Sessions"
|
||||
aliases: [agent-teams, claude-agent-teams, multi-session-teams]
|
||||
tags: [claude-code, multi-agent, parallelism, orchestration, experimental]
|
||||
sources: [raw/Orchestrate teams of Claude Code sessions.md]
|
||||
created: 2026-04-17
|
||||
updated: 2026-04-17
|
||||
---
|
||||
|
||||
# Agent Teams
|
||||
|
||||
Agent teams let you coordinate multiple Claude Code instances working together. One session acts as **team lead**; the rest are **teammates** — independent sessions that communicate directly with each other via a shared task list and mailbox.
|
||||
|
||||
> **Experimental** — requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in `settings.json` or env. Needs Claude Code v2.1.32+.
|
||||
|
||||
---
|
||||
|
||||
## Enabling
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
| Component | Role |
|
||||
|-----------|------|
|
||||
| **Team lead** | Main session — spawns teammates, owns task list, synthesizes results |
|
||||
| **Teammates** | Independent Claude Code instances with their own context windows |
|
||||
| **Task list** | Shared work items; teammates claim and complete them (`~/.claude/tasks/{team}/`) |
|
||||
| **Mailbox** | Async messaging between any two agents by name |
|
||||
|
||||
- Team config stored at `~/.claude/teams/{team-name}/config.json` — do **not** edit by hand
|
||||
- Task claiming uses file locking to prevent race conditions
|
||||
- Dependencies are managed automatically: blocked tasks unblock when their dependency completes
|
||||
|
||||
---
|
||||
|
||||
## Agent Teams vs Subagents
|
||||
|
||||
| | Subagents | Agent Teams |
|
||||
|--|-----------|-------------|
|
||||
| **Communication** | Report results to main agent only | Teammates message each other directly |
|
||||
| **Coordination** | Main agent manages all work | Shared task list with self-coordination |
|
||||
| **Best for** | Focused tasks where only result matters | Complex work requiring discussion/collaboration |
|
||||
| **Token cost** | Lower | Higher (each teammate is a separate Claude instance) |
|
||||
|
||||
Use [[wiki/claude-code/custom-subagents|subagents]] when workers only need to report back. Use agent teams when teammates need to share findings and challenge each other.
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
**Strong use cases (parallel exploration adds value):**
|
||||
- Research & review — multiple angles investigated simultaneously
|
||||
- New modules — each teammate owns a separate piece
|
||||
- Debugging with competing hypotheses — teammates test theories in parallel
|
||||
- Cross-layer changes — frontend, backend, tests each owned by a different teammate
|
||||
|
||||
**Avoid agent teams for:**
|
||||
- Sequential tasks
|
||||
- Same-file edits
|
||||
- Work with many interdependencies (use a single session or subagents instead)
|
||||
|
||||
---
|
||||
|
||||
## Display Modes
|
||||
|
||||
| Mode | How | Requires |
|
||||
|------|-----|----------|
|
||||
| **in-process** (default) | All teammates in one terminal; `Shift+Down` cycles through | Nothing |
|
||||
| **split-panes** | Each teammate gets its own pane | tmux or iTerm2 + `it2` CLI |
|
||||
|
||||
Override in `~/.claude.json`:
|
||||
```json
|
||||
{ "teammateMode": "in-process" }
|
||||
```
|
||||
Or per session: `claude --teammate-mode in-process`
|
||||
|
||||
---
|
||||
|
||||
## Control Patterns
|
||||
|
||||
### Spawn a team (natural language)
|
||||
```text
|
||||
Create an agent team: one teammate on UX, one on architecture, one as devil's advocate.
|
||||
```
|
||||
|
||||
### Specify teammates and models
|
||||
```text
|
||||
Create a team with 4 teammates. Use Sonnet for each teammate.
|
||||
```
|
||||
|
||||
### Require plan approval before implementation
|
||||
```text
|
||||
Spawn an architect teammate to refactor auth. Require plan approval before any changes.
|
||||
```
|
||||
Lead reviews → approves or rejects with feedback → teammate revises if rejected → implements when approved.
|
||||
|
||||
### Direct teammate messaging
|
||||
- **In-process**: `Shift+Down` to cycle, type to message, `Enter` to view session, `Escape` to interrupt, `Ctrl+T` for task list
|
||||
- **Split-pane**: click into a pane
|
||||
|
||||
### Shutdown & cleanup
|
||||
```text
|
||||
Ask the researcher teammate to shut down
|
||||
Clean up the team # run after all teammates are stopped
|
||||
```
|
||||
Always run cleanup from the **lead**, not a teammate.
|
||||
|
||||
---
|
||||
|
||||
## Quality Gates via Hooks
|
||||
|
||||
| Hook | Trigger | Exit 2 = |
|
||||
|------|---------|----------|
|
||||
| `TeammateIdle` | Teammate about to go idle | Send feedback, keep teammate working |
|
||||
| `TaskCreated` | Task being created | Block creation with feedback |
|
||||
| `TaskCompleted` | Task being marked done | Block completion with feedback |
|
||||
|
||||
See [[wiki/claude-code/overview|Claude Code overview]] for general hooks documentation.
|
||||
|
||||
---
|
||||
|
||||
## Permissions & Context
|
||||
|
||||
- Teammates inherit the **lead's permission settings** at spawn time (including `--dangerously-skip-permissions`)
|
||||
- Each teammate loads project context fresh: `CLAUDE.md`, MCP servers, skills — but **not** the lead's conversation history
|
||||
- Include task-specific details in the spawn prompt
|
||||
- Teammates can reference [[wiki/claude-code/custom-subagents|subagent definitions]] by name for reusable roles
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Start with 3–5 teammates** — balances parallelism with coordination overhead
|
||||
- **5–6 tasks per teammate** — prevents context-switching overload
|
||||
- **Break work by file ownership** — two teammates editing the same file causes overwrites
|
||||
- **Begin with research/review tasks** if new to agent teams (no code-conflict risk)
|
||||
- **Monitor and steer** — don't let teams run unattended too long
|
||||
- **Tell the lead to wait** if it starts implementing instead of delegating: `"Wait for your teammates to complete their tasks before proceeding"`
|
||||
|
||||
---
|
||||
|
||||
## Limitations (Experimental)
|
||||
|
||||
- No session resumption for in-process teammates (`/resume`/`/rewind` don't restore them)
|
||||
- Task status can lag — may need manual nudge
|
||||
- Shutdown can be slow (teammate finishes current request first)
|
||||
- One team per lead session
|
||||
- No nested teams — teammates cannot spawn their own teams
|
||||
- Lead is fixed for the team's lifetime
|
||||
- Split panes not supported in VS Code terminal, Windows Terminal, or Ghostty
|
||||
|
||||
---
|
||||
|
||||
## Key Takeaways
|
||||
|
||||
- Agent teams are **experimental** and token-expensive — each teammate is a full Claude instance
|
||||
- The core advantage over subagents: **teammates communicate directly** and share a task list with self-coordination
|
||||
- **3–5 teammates, 5–6 tasks each** is the recommended starting size
|
||||
- The **lead controls everything** — spawning, task assignment, cleanup; never run cleanup from a teammate
|
||||
- Use **hooks** (`TeammateIdle`, `TaskCreated`, `TaskCompleted`) to enforce quality gates automatically
|
||||
- Best ROI on research, parallel review, and competing-hypotheses debugging — not sequential or same-file work
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
- `raw/Orchestrate teams of Claude Code sessions.md`
|
||||
- Official docs: https://code.claude.com/docs/en/agent-teams
|
||||
Loading…
Add table
Reference in a new issue