diff --git a/01 Projects/Barclays-banner-builder/Barclays Banner Builder.md b/01 Projects/Barclays-banner-builder/Barclays Banner Builder.md index e98211c..f45ccfb 100644 --- a/01 Projects/Barclays-banner-builder/Barclays Banner Builder.md +++ b/01 Projects/Barclays-banner-builder/Barclays Banner Builder.md @@ -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 | diff --git a/99 Daily/2026-04-17.md b/99 Daily/2026-04-17.md index c606f9d..5650716 100644 --- a/99 Daily/2026-04-17.md +++ b/99 Daily/2026-04-17.md @@ -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. diff --git a/raw/Observability with OpenTelemetry.md b/raw/_processed/Observability with OpenTelemetry.md similarity index 100% rename from raw/Observability with OpenTelemetry.md rename to raw/_processed/Observability with OpenTelemetry.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index 8296d35..2bf6198 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -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 | diff --git a/wiki/claude-code/_index.md b/wiki/claude-code/_index.md index b488e5f..aeefba1 100644 --- a/wiki/claude-code/_index.md +++ b/wiki/claude-code/_index.md @@ -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 | diff --git a/wiki/claude-code/agent-teams.md b/wiki/claude-code/agent-teams.md new file mode 100644 index 0000000..e2eb380 --- /dev/null +++ b/wiki/claude-code/agent-teams.md @@ -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