Multi-Agent Collaboration for Team and Friends
TypeScript agent-automationagent-orchestrationagent-workflowai-agentsai-collaborationai-memoryai-workforceautonomous-agentsclaude-codeclaude-code-skillscodexcoding-agentmulti-agentmultiple-agentone-person-businessone-person-companyone-person-teamopencodesolopreneur
docs: reorganize README by module with architecture diagrams and getting started guide
Gener1ab8638dda92
diff --git a/README.md b/README.mdindex ff1d4cb68..846838988 100644--- a/README.md+++ b/README.md@@ -1,49 +1,114 @@# Alook-A stripped-down AI agent task execution platform. Chat with AI agents (Claude Code, Codex, OpenCode) through a web UI, powered by a local daemon that manages agent runtimes.+Email-driven autonomous agent platform. Users create AI agents with email handles — when an agent receives an email, a runtime machine executes the task using Claude or Codex and streams results back to the dashboard in real time.## Architecture+```mermaid+graph TD+ SMTP["Inbound Email (SMTP)"] --> EW++ EW["Email Worker<br/><i>parse, store R2, create event</i>"]+ EW -- "service binding<br/>POST /api/email/notify" --> WS++ Browser["Browser (React)"] <-- "WebSocket<br/>(via WS-DO)" --> WS+ WS["Web Service<br/><i>Next.js on Cloudflare Workers</i>"]+ WS <-- "HTTP polling" --> CLI["CLI Daemon<br/><i>(Bun runtime)</i>"]++ WS -- "service binding" --> DO["WS-DO<br/><i>Browser-only real-time<br/>WebSocket channels</i>"]```-Browser → Next.js on Cloudflare Workers (D1 + R2) ← CLI Daemon- ↕ ↕- Email Worker (inbound) WebSocket DO (realtime)++### Service Relationships++```mermaid+graph TD+ subgraph CF["Cloudflare Edge"]+ subgraph Workers+ EW["Email Worker"]+ WS["Web Service"]+ DO["WS-DO<br/>(Durable Objects)"]+ end+ subgraph Infrastructure+ D1["D1 Database<br/>(alook-app)"]+ R2["R2 Bucket<br/>(alook-emails)"]+ end+ BC["Web Dashboard"]+ end++ subgraph RM["Runtime Machine"]+ CLI["CLI Daemon<br/>- Heartbeat (3s)<br/>- Event poll (2s)<br/>- Task execution<br/> (Claude / Codex)"]+ end++ EW -- "service binding" --> WS+ WS -- "service binding" --> DO++ EW -- "D1 r/w" --> D1+ EW -- "R2 r/w" --> R2+ WS -- "D1 r/w" --> D1+ WS -- "R2 r/w" --> R2+ DO -- "D1 r/w" --> D1++ DO -- "WebSocket" --> BC+ WS -- "REST API (polling)" --> CLI```-| Package | Description |-|---------|-------------|-| `src/shared` | Shared types, D1 schema, query modules, validators (`@alook/shared`) |-| `src/web` | Next.js App Router on Cloudflare Workers — frontend + API routes |-| `src/cli` | Commander.js CLI + daemon that spawns agent subprocesses |-| `src/email-worker` | Cloudflare Worker for inbound email handling |-| `src/ws-do` | Cloudflare Durable Object for WebSocket connections |+## Services-## Quick Start+| Service | Package | Location | Runtime | Purpose |+|---------|---------|----------|---------|---------|+| **Web** | `@alook/web` | `src/web` | Cloudflare Workers (OpenNext) | Dashboard, REST API, auth, database |+| **Email Worker** | `@alook/email-worker` | `src/email-worker` | Cloudflare Worker | Inbound email parsing, storage, event creation |+| **WS-DO** | `@alook/ws-do` | `src/ws-do` | Cloudflare Durable Objects | Real-time WebSocket channels per agent/user |+| **CLI** | `@alook/cli` | `src/cli` | Bun | Runtime daemon, task execution, agent orchestration |+| **Shared** | `@alook/shared` | `src/shared` | Library | Types, constants, validation utilities |++## Tech Stack++- **Frontend:** Next.js, React, Tailwind CSS, Base UI+- **Backend:** Next.js API routes on Cloudflare Workers+- **Auth:** Better Auth+- **Database:** Cloudflare D1 (SQLite)+- **Storage:** Cloudflare R2+- **Real-time:** WebSockets via Durable Objects+- **AI Runtimes:** Claude (Agent SDK), Codex (OpenAI SDK)+- **CLI Runtime:** Bun+- **Monorepo:** Turborepo + pnpm workspaces+- **Testing:** Vitest++## Getting Started```bash-pnpm install # Install deps-pnpm dev # Start dev servers (web + email-worker)-pnpm dev:cli # In another terminal — start CLI daemon+pnpm clean # remove node_modules, build artifacts, local D1 state+pnpm install # install dependencies+pnpm db:migrate # set up local D1 database+pnpm dev # start web + workers (excludes CLI)```-## Commands+## Development```bash-pnpm dev # Start all dev servers-pnpm dev:web # Web dev server only-pnpm dev:cli # CLI dev mode-pnpm dev:email # Email worker dev server-pnpm build # Build web + CLI-pnpm test # Run all tests (turbo)-pnpm typecheck # TypeScript check (turbo)-pnpm db:migrate # Apply D1 migrations locally-pnpm db:reset # Reset local D1 and re-apply migrations+pnpm install # install dependencies+pnpm dev # start web + workers (excludes CLI)+pnpm dev:cli # start CLI separately (requires Bun)+pnpm db:migrate # run D1 migrations locally+pnpm db:reset # wipe local D1 and re-migrate+pnpm test # run all tests+pnpm typecheck # typecheck all packages```-## How It Works+### Individual services++```bash+pnpm dev:web # Next.js dev server on :3000+pnpm dev:email # Email worker on :8788+pnpm dev:cli # CLI daemon (Bun)+pnpm dev:send <from> <to> [subject] [body] # simulate inbound email+```++## Key Workflows++**Email reception:** SMTP -> Email Worker -> parse & store in R2/D1 -> create event -> notify web service -> web service broadcasts via WS-DO to browser -> CLI picks up event via HTTP polling++**Task execution:** CLI receives event -> creates task record -> runs Claude/Codex agent with prompt -> streams output chunks to API -> marks complete -> dashboard updates in real time-1. Daemon detects installed agent CLIs (`claude`, `codex`, `opencode`) and registers runtimes with the server-2. Create an agent in the UI and link it to a runtime-3. Send a message in a conversation — server enqueues a task-4. Daemon claims the task, runs the agent CLI, streams results back-5. Frontend receives updates via WebSocket and displays output in real-time+**Runtime registration:** CLI `register <token>` -> detects local runtimes (claude, codex) -> registers with Web API -> starts daemon (heartbeat, polling)