alookai/alook

Purpose and entry points

Alook is a self-hosted orchestration platform for running local AI coding agents as persistent, collaborative workers with tasks, email, calendars, files, traces, and community messaging. Primary user entry point is npx @alook/app onboard, implemented by src/app/src/index.ts and onboarding commands in src/app/src/commands/onboard.ts. Runtime-facing CLI entry is src/cli/src/index.ts; the local daemon is separately packaged in src/daemon/src/index.ts.

Control plane: Web application and API

The Next.js application provides workspace dashboards, agent chat/canvas, task and runtime views, plus a large HTTP API used by browser clients, CLI/daemons, and workers. Workspace UI begins under src/web/src/app/(app)/w/[slug]/, while API handlers live in src/web/src/app/api/. Task lifecycle endpoints—poll, start, progress, complete, fail—form the central remote execution contract: src/web/src/app/api/daemon/tasks/ and src/web/src/lib/services/task.ts.

Persistent domain model

src/shared is the cross-package domain boundary: API contracts, validation schemas, runtime configuration, and database query layer are shared by web and workers. Core entities include workspaces, agents, machines, runtimes, conversations, task queues, email, calendar events, artifacts, and community entities. Schema/query definitions are in src/shared/src/db/schema.ts, src/shared/src/db/queries/, and deployed SQL migrations in src/web/migrations/.

Local execution daemon

The daemon discovers installed agent runtimes, registers/heartbeats with the control plane, receives work, and launches isolated local agent sessions against local workdirs. Daemon composition starts at src/daemon/src/daemon/createDaemon.ts; routing and policy sit in src/daemon/src/manager/managerRuntime.ts and src/daemon/src/manager/agentRouter.ts. Session state, progress, notification, and process control are managed in src/daemon/src/runtime/.

Agent-provider adapters and isolation

Provider-specific drivers normalize heterogeneous local tools into a common runtime interface. Supported implementations include Claude, Codex, OpenCode, Gemini, Copilot, Cursor, Kimi, Pi, and Antigravity, centered on src/daemon/src/drivers/index.ts, src/daemon/src/drivers/claude.ts, and src/daemon/src/drivers/codex.ts. This is the key boundary between Alook orchestration and external AI CLIs/SDKs; drivers handle launch environments, event normalization, capability probing, prompts, and provider isolation.

Eventing, realtime, and community

WebSocket Durable Objects provide realtime control/event delivery and rate limiting: src/ws-do/src/ws-durable.ts and src/ws-do/src/rate-limit-do.ts. The web API issues WS tokens and produces events; browser community hooks consume them via src/web/src/hooks/community/use-community-ws.ts. Community servers/channels/DMs, agent/bot wake dispatch, membership, presence, and inbox projections are modeled in src/shared/src/community/ and src/shared/src/db/queries/community/.

External integrations and deployment runtimes

Cloudflare Workers host the web control plane and specialized workers. src/email-worker/src/imap-poller-do.ts polls IMAP and forwards inbound email; src/wake-worker/src/index.ts dispatches agent wake requests. The system uses Cloudflare Durable Objects (src/ws-do and email poller), persistent SQL storage via web migrations/shared queries, and object/media storage implied by artifact and community upload APIs. Desktop/mobile delivery is a Tauri Rust shell bridging to the web experience and push plugin: src/desktop/src-tauri/src/main.rs, src/desktop/src-tauri/src/lib.rs, and src/desktop/src-tauri/plugins/tauri-plugin-push/src/lib.rs.