CLAUDE.md · 777genius/agent-teams-ai

Sections

1. Tech Stack
2. Commands
3. Git delivery
4. Git commits
5. Path Aliases
6. Features Architecture
7. Data Sources
8. Critical Concepts
9. Error Handling
10. Performance
11. Troubleshooting
12. TypeScript Conventions

First lines (shown under the repo's AGPL-3.0 license)

# Agent Teams

A new approach to task management with AI agent teams. Assemble agent teams with different roles that work autonomously in parallel, communicate with each other, create and manage their own tasks, review code, and collaborate across teams. You manage everything through a kanban board — like a CTO with an AI engineering team.

Key capabilities:

- **Agent Teams** — create teams with roles, agents work autonomously in parallel
- **Cross-team communication** — agents message each other within and across teams
- **Kanban board** — tasks change status in real-time as agents work
- **Code review** — diff view per task (accept/reject/comment), similar to Cursor
- **Solo mode** — single agent with self-managed tasks, expandable to full team
- **Live process section** — see running agents, open URLs in browser
- **Direct messaging** — send messages to any agent, comment on tasks, add quick actions on kanban cards
- **Deep session analysis** — bash commands, reasoning, subprocesses breakdown
- **Context monitoring** — token usage by category (CLAUDE.md, tool outputs, thinking, team coordination)
- **Built-in code editor** — edit files with Git support without leaving the app
- **MCP integration** — built-in mcp-server for external tools and agent plugins
- **Post-compact context recovery** — restores team-management instructions after context compaction
- **Notification system** — alerts on task completion, agent attention needed, errors
- **Zero-setup onboarding** — built-in runtime detection and provider authentication for Claude, Codex, and OpenCode

100% free, open source, and local-first. The app uses available Claude/Codex/OpenCode provider access instead of forcing a single app-level API-key setup.

## Tech Stack

Electron 40.x, React 19.x, TypeScript 5.x, Tailwind CSS 3.x, Zustand 4.x

## Commands

Always use pnpm (not npm/yarn) for this project.
Workspace membership is canonical in `pnpm-workspace.yaml`; do not re-add root `package.json.workspaces`, because npm subproject installs in Codex Cloud must treat nested packages as standalone projects.
Do NOT run `pnpm lint:fix` unless the user explicitly asks for it — it interferes with agents running in parallel.
When running build/typecheck/test commands, pipe through `tail -20` to avoid flooding the context window (e.g. `pnpm typecheck 2>&1 | tail -20`).

- Hard guardrails: [`AGENT_CRITICAL_GUARDRAILS.md`](AGENT_CRITICAL_GUARDRAILS.md)

- `pnpm install` - Install dependencies
- `pnpm dev` - Desktop Electron app with hot reload
- `pnpm build` - Production build
- `pnpm typecheck` - Canonical type check using the project's pinned native TypeScript 7 compiler (do not additionally run global `tsc7`)
- `pnpm guard:source-file-size` - Reject new production files above 800 lines and prevent frozen legacy files from growing
- `pnpm guard:team-provisioning-architecture` - Prevent new facade inheritance and implicit whole-service coupling in Team Provisioning
- `pnpm lint:fix` - Lint and auto-fix
- `pnpm format` - Format code
- `pnpm test` - Run all vitest tests
- `pnpm test:watch` - Watch mode
- `pnpm test:coverage` - Coverage report
- `pnpm test:coverage:critical` - Critical path coverage
- `pnpm test:chunks` - Chunk building tests
- `pnpm test:semantic` - Semantic step extraction tests
- `pnpm test:noise` - Noise filtering tests
- `pnpm test:task-filtering` - Task tool filtering tests
- `pnpm check` - Full quality gate (types + lint + test + build)
- `pnpm fix` - Lint fix + format
- `pnpm quality` - Full check + format check + knip

## Git delivery

Follow [docs/GIT_DELIVERY_POLICY.md](docs/GIT_DELIVERY_POLICY.md) for PR/CI
delivery and the one-time exception for an explicit personal owner request
to push directly to main. Read that policy before committing or pushing.

## Git commits

Use normal, human-readable messages. Do not add tool-attribution trailers (for example `Made-with: …`) to commit messages.

## Path Aliases

Use path aliases for imports:

- `@main/*` → `src/main/*`
- `@renderer/*` → `src/renderer/*`
- `@shared/*` → `src/shared/*`
- `@preload/*` → `src/preload/*`

## Features Architecture

**All new medium and large features should follow the canonical slice standard in [`docs/FEATURE_ARCHITECTURE_STANDARD.md`](docs/FEATURE_ARCHITECTURE_STANDARD.md).**

Default location:

- `src/features/<feature-name>/`

Reference implementation:

- `src/features/recent-projects`

Feature-local guidance:

- `src/features/CLAUDE.md`

Team Provisioning migration guidance:

- `docs/team-management/team-provisioning-target-architecture.md`
- new provisioning behavior must use explicit composition and focused ports; do not add facade-inheritance layers or whole-service host casts

Legacy note:

- `src/renderer/features/*` still exists for older renderer-only slices
- do not use `src/renderer/features/*` as the default for new cross-process features
- thin renderer-only slices may still stay local when they do not need `core/`, transport wiring, or multi-process boundaries

## Data Sources

~/.claude/projects/{encoded-path}/\*.jsonl - Session files
~/.claude/todos/{sessionId}.json - Todo data

Path encoding: `/Users/name/project` → `-Users-name-project`

## Critical Concepts

### Agent Blocks

- Use `wrapAgentBlock(text)` from `@shared/constants/agentBlocks` to wrap agent-only content.
  Do NOT manually concatenate `AGENT_BLOCK_OPEN/CLOSE` — the wrapper handles trimming and formatting.
- `stripAgentBlocks(text)` — removes agent blocks for UI display
- `unwrapAgentBlock(block)` — extracts content from a single block
- Agent blocks are hidden from the user in UI, used for internal instructions between agents.

### isMeta Flag

- `isMeta: false` = Real user message (creates new chunks)
- `isMeta: true` = Internal message (tool results, system-generated)

### Chunk Structure

Independent chunk types for timeline visualization:

- **UserChunk**: Single user message with metrics
- **AIChunk**: All assistant responses with tool executions and spawned subagents
- **SystemChunk**: Command output/system messages
- **CompactChunk**: System metadata/structural messages

Each chunk has: timestamp, duration, metrics (tokens, cost, tools)

### Task/Subagent Filtering

Task tool_use blocks are filtered when subagent exists
Keep orphaned Task calls (no matching subagent) for visibility.

### Agent Teams

Agent Teams is this app's orchestration layer across Claude, Codex, and OpenCode runtimes.
For Claude runtime behavior, also track Anthropic's upstream agent-team docs: https://code.claude.com/docs/en/agent-teams

#### Debugging Team Launches And Teammates

- Use [`docs/team-management/debugging-agent-teams.md`](docs/team-management/debugging-agent-teams.md) when a team launch hangs, a teammate remains `registered`, OpenCode shows `bootstrap unconfirmed`, messages are missing, or Task Log Stream looks wrong.
- For implementation and refactoring shape, follow [`docs/team-management/team-provisioning-target-architecture.md`](docs/team-management/team-provisioning-target-architecture.md); the debugging runbook remains the source of truth for runtime diagnosis.
- Always correlate UI diagnostics with persisted files under `~/.claude/teams/<teamName>/`, live process state, and runtime-specific evidence before changing code.
- For OpenCode secondary lanes, do not confuse primary filesystem readiness with lane bootstrap readiness. A missing OpenCode inbox during primary launch is not automatically a bug.
- Do not treat `member_briefing` as runtime evidence. OpenCode deliverability requires lane-scoped committed runtime evidence such as `opencode-sessions.json` plus its manifest entry.

#### Message Delivery Architecture

- **Lead** reads ONLY stdin (stream-json). Messages to lead must go through `relayLeadInboxMessages()` which converts inbox entries to stdin.
- **Native teammates** are independent CLI/process teammates. Claude/Codex-style teammates read their own inbox files between turns; no relay through the lead is needed.
- **OpenCode secondary lanes** do not watch teammate inbox files. User DMs are persisted to `inboxes/{member}.json`, then delivered through the OpenCode runtime bridge with explicit delivery proof.
- **User → Teammate DM**: UI writes to `inboxes/{member}.json` with `from: "user"`. Native teammates read it directly; OpenCode teammates receive it through runtime delivery.
- **Teammate → User response**: Teammate writes to `inboxes/user.json` or uses the runtime-specific Agent Teams message tool that persists there. UI reads all inbox files including `user.json` via `TeamInboxReader`.