Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

docs: reorganize README by module with architecture diagrams and getting started guide

Gener1ab8638dda92
diff --git a/README.md b/README.md
index 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/>&nbsp; (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)