223 lines
9.2 KiB
Markdown
223 lines
9.2 KiB
Markdown
# CLAUDE.md — Agent Orchestrator
|
|
|
|
## What This Project Is
|
|
|
|
An open-source, agent-agnostic system for orchestrating parallel AI coding agents. Any coding agent, any repo, any issue tracker, any runtime. The system manages session lifecycle, tracks PR/CI/review state, auto-handles routine issues (CI failures, review comments), and pushes notifications to humans only when their judgment is needed.
|
|
|
|
**Core principle: Push, not pull.** The human spawns agents, walks away, and gets notified when needed.
|
|
|
|
## Tech Stack
|
|
|
|
- **Language**: TypeScript throughout (ESM, Node 20+, strict mode)
|
|
- **Monorepo**: pnpm workspaces
|
|
- **Web**: Next.js 15 (App Router) + Tailwind CSS
|
|
- **CLI**: Commander.js
|
|
- **Config**: YAML + Zod validation
|
|
- **Real-time**: Server-Sent Events
|
|
- **State**: Flat metadata files + JSONL event log
|
|
- **Linting**: ESLint (flat config) + Prettier
|
|
- **Testing**: vitest
|
|
|
|
## Architecture
|
|
|
|
8 plugin slots — every abstraction is swappable:
|
|
|
|
| Slot | Interface | Default Plugin |
|
|
| --------- | --------------------- | -------------- |
|
|
| Runtime | `Runtime` | tmux |
|
|
| Agent | `Agent` | claude-code |
|
|
| Workspace | `Workspace` | worktree |
|
|
| Tracker | `Tracker` | github |
|
|
| SCM | `SCM` | github |
|
|
| Notifier | `Notifier` | desktop |
|
|
| Terminal | `Terminal` | iterm2 |
|
|
| Lifecycle | (core, not pluggable) | — |
|
|
|
|
All interfaces are defined in `packages/core/src/types.ts`. **Read this file first** — it is the source of truth for all abstractions.
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
packages/
|
|
core/ — @agent-orchestrator/core (types, config, services)
|
|
cli/ — @agent-orchestrator/cli (the `ao` command)
|
|
web/ — @agent-orchestrator/web (Next.js dashboard)
|
|
plugins/
|
|
runtime-tmux/ — tmux session runtime
|
|
runtime-process/ — child process runtime
|
|
agent-claude-code/ — Claude Code adapter
|
|
agent-codex/ — Codex CLI adapter
|
|
agent-aider/ — Aider adapter
|
|
workspace-worktree/ — git worktree isolation
|
|
workspace-clone/ — git clone isolation
|
|
tracker-github/ — GitHub Issues tracker
|
|
tracker-linear/ — Linear tracker
|
|
scm-github/ — GitHub PRs, CI, reviews
|
|
notifier-desktop/ — OS desktop notifications
|
|
notifier-slack/ — Slack notifications
|
|
notifier-webhook/ — Generic webhook notifications
|
|
terminal-iterm2/ — macOS iTerm2 tab management
|
|
terminal-web/ — xterm.js web terminal
|
|
```
|
|
|
|
## Code Conventions
|
|
|
|
### TypeScript (MUST follow)
|
|
|
|
- **ESM modules** — all packages use `"type": "module"`
|
|
- **`.js` extensions in imports** — required for ESM: `import { foo } from "./bar.js"`
|
|
- **`node:` prefix for builtins** — `import { readFileSync } from "node:fs"`, never bare `"fs"`
|
|
- **Strict mode** — `"strict": true` in all tsconfig
|
|
- **`type` imports** — use `import type { Foo }` for type-only imports (enforced by ESLint)
|
|
- **No `any`** — use `unknown` and narrow with type guards. `any` is an ESLint error
|
|
- **No `as unknown as T` casts** — validate data instead of unsafe casting
|
|
- **Prefer `const`** — `let` only when reassignment is needed, never `var`
|
|
- **Semicolons** — always use them
|
|
- **Double quotes** — for strings (enforced by Prettier)
|
|
- **2-space indentation** — (enforced by Prettier)
|
|
|
|
### Plugin Pattern (MUST follow)
|
|
|
|
Every plugin exports a `PluginModule` with type-safe `satisfies`:
|
|
|
|
```typescript
|
|
import type { PluginModule, Runtime } from "@agent-orchestrator/core";
|
|
|
|
const manifest = {
|
|
name: "tmux",
|
|
slot: "runtime" as const,
|
|
description: "Runtime plugin: tmux sessions",
|
|
version: "0.1.0",
|
|
};
|
|
|
|
function create(): Runtime {
|
|
return {
|
|
name: "tmux",
|
|
// ... implement interface methods
|
|
};
|
|
}
|
|
|
|
export default { manifest, create } satisfies PluginModule<Runtime>;
|
|
```
|
|
|
|
**Do NOT** use `const plugin = { ... }; export default plugin;` — always use inline `satisfies` for compile-time type checking.
|
|
|
|
### Shell Command Execution (MUST follow)
|
|
|
|
- **Always use `execFile`** (or `spawn`) from `node:child_process` — NEVER `exec`
|
|
- `exec` runs through a shell and is vulnerable to injection
|
|
- `execFile` passes args as an array, bypassing shell interpretation
|
|
- **Always add timeouts** — `{ timeout: 30_000 }` for external commands
|
|
- **Escape user-provided values** — never interpolate into command strings
|
|
- **Shell escaping**: Do NOT use `JSON.stringify` for shell escaping — it is not a shell escaping function
|
|
|
|
```typescript
|
|
// GOOD
|
|
import { execFile } from "node:child_process";
|
|
import { promisify } from "node:util";
|
|
const execFileAsync = promisify(execFile);
|
|
const { stdout } = await execFileAsync("git", ["branch", "--show-current"], { timeout: 30_000 });
|
|
|
|
// BAD — shell injection risk
|
|
import { exec } from "node:child_process";
|
|
exec(`git checkout ${branchName}`); // branchName could contain ; rm -rf /
|
|
```
|
|
|
|
### Error Handling
|
|
|
|
- Throw typed errors, don't return error codes
|
|
- Plugin methods should throw if they can't do their job
|
|
- The core services catch and handle plugin errors
|
|
- **Always wrap `JSON.parse`** in try/catch — corrupted metadata should not crash the system
|
|
- **Guard external data** — validate types from API/CLI/file inputs before using them
|
|
|
|
### Naming
|
|
|
|
- Files: `kebab-case.ts`
|
|
- Types/Interfaces: `PascalCase`
|
|
- Functions/variables: `camelCase`
|
|
- Constants: `UPPER_SNAKE_CASE` only for true constants (env vars, regex patterns)
|
|
- Plugin names: `kebab-case` matching directory name
|
|
- Test files: `*.test.ts` co-located with source, or in `__tests__/` directory
|
|
|
|
### Imports Order
|
|
|
|
1. Node builtins (`node:fs`, `node:path`, etc.)
|
|
2. External packages (`commander`, `chalk`, `yaml`, etc.)
|
|
3. Workspace packages (`@agent-orchestrator/core`)
|
|
4. Relative imports (`./foo.js`)
|
|
|
|
### Testing
|
|
|
|
- Use **vitest** for all tests
|
|
- Mock external dependencies (`child_process`, `fs`, HTTP calls)
|
|
- Co-locate test files: `src/foo.test.ts` or `src/__tests__/foo.test.ts`
|
|
- Test edge cases: corrupted data, missing files, timeout, concurrent access
|
|
|
|
## Building & Development
|
|
|
|
```bash
|
|
pnpm install # install all deps
|
|
pnpm build # build all packages
|
|
pnpm typecheck # typecheck all packages
|
|
pnpm lint # ESLint check
|
|
pnpm lint:fix # ESLint auto-fix
|
|
pnpm format # Prettier format
|
|
pnpm format:check # Prettier check (CI)
|
|
pnpm test # run all tests
|
|
```
|
|
|
|
### Before Committing
|
|
|
|
Always run lint and typecheck:
|
|
|
|
```bash
|
|
pnpm lint && pnpm typecheck
|
|
```
|
|
|
|
Fix any issues before pushing. CI will reject PRs that fail lint or typecheck.
|
|
|
|
## Config
|
|
|
|
- Config is loaded from `agent-orchestrator.yaml` (see `.yaml.example`)
|
|
- All paths support `~` expansion
|
|
- Per-project overrides for plugins and reactions
|
|
- Validated with Zod schema at load time
|
|
|
|
## Reference Implementation
|
|
|
|
The `scripts/` directory contains the original bash scripts that this TypeScript codebase replaces. Use them as behavioral specifications:
|
|
|
|
| Script | What It Specifies |
|
|
| ------------------------- | ------------------------------------------------------ |
|
|
| `claude-ao-session` | Session lifecycle (spawn, list, kill, cleanup) |
|
|
| `claude-dashboard` | Web dashboard, API, activity detection |
|
|
| `claude-batch-spawn` | Batch spawning with duplicate detection |
|
|
| `send-to-session` | Smart message delivery (busy detection, wait-for-idle) |
|
|
| `claude-status` | JSONL introspection, live branch detection |
|
|
| `claude-review-check` | PR review scanning, fix prompt generation |
|
|
| `claude-bugbot-fix` | Automated comment detection + fixes |
|
|
| `claude-session-status` | Activity classification (working/idle/blocked) |
|
|
| `get-claude-session-info` | Agent introspection (session ID, summary extraction) |
|
|
|
|
## Key Design Decisions
|
|
|
|
1. **Stateless orchestrator** — no database, just flat metadata files + event log
|
|
2. **Plugins implement interfaces** — every plugin is a pure implementation of an interface from `types.ts`
|
|
3. **Push notifications** — the Notifier is the primary human interface, not the dashboard
|
|
4. **Two-tier event handling** — auto-handle routine issues (CI, reviews), notify human only when judgment is needed
|
|
5. **Backwards-compatible metadata** — flat key=value files matching the existing bash script format
|
|
6. **Security first** — `execFile` not `exec`, validate all external input, escape strings for target context
|
|
|
|
## Common Mistakes to Avoid
|
|
|
|
- Using `exec` instead of `execFile` — security vulnerability
|
|
- Using `JSON.stringify` for shell escaping — does not escape `$`, backticks, `$()`
|
|
- Missing `.js` extension in local imports — will fail at runtime with ESM
|
|
- Using bare `"fs"` instead of `"node:fs"` — inconsistent, may break in edge cases
|
|
- Casting with `as unknown as T` — bypasses type safety, crashes on bad data
|
|
- `export default plugin` without `satisfies PluginModule<T>` — loses type checking
|
|
- Interpolating user input into shell commands, AppleScript, or GraphQL queries
|
|
- Forgetting to clean up setInterval/setTimeout on disconnect/destroy
|
|
- Using `on("exit")` instead of `once("exit")` for one-time handlers
|