Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

fix: issue task prompt

Gus9e79489b75c4
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..be0e742b9
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,131 @@
+# Contributing to Alook
+
+Thanks for your interest in contributing to Alook. This guide covers everything you need to get started.
+
+## Prerequisites
+
+- **Node.js** ≥ 18
+- **pnpm** ≥ 9
+- **Bun** (for CLI development)
+
+## Setup
+
+```bash
+git clone https://github.com/alookai/alook.git
+cd alook
+pnpm install
+pnpm db:migrate
+pnpm dev
+```
+
+This starts the web app and workers locally. To work on the CLI separately:
+
+```bash
+pnpm dev:cli
+```
+
+## Project Structure
+
+Alook is a monorepo with five packages:
+
+| Package | Location | What it does |
+|---------|----------|-------------|
+| `@alook/web` | `src/web` | Next.js dashboard, REST API, auth, database |
+| `@alook/cli` | `src/cli` | Runtime daemon, task execution, agent orchestration |
+| `@alook/shared` | `src/shared` | Types, constants, DB schema, validation |
+| `@alook/email-worker` | `src/email-worker` | Inbound email parsing and storage |
+| `@alook/ws-do` | `src/ws-do` | Real-time WebSocket channels |
+
+## Making Changes
+
+### 1. Branch off main
+
+```bash
+git checkout -b feat/your-feature
+```
+
+### 2. Write your code
+
+A few ground rules:
+
+- **Scope DB queries by workspace ID** — every query must be scoped. This is a security boundary.
+- **Services are stateless** — all state belongs in the database or on disk, never in memory.
+- **Use Drizzle ORM** — no raw SQL unless there's no ORM equivalent.
+- **Write tests** — only skip if the change is already covered by existing tests.
+
+### 3. Validate before pushing
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm test
+```
+
+All three must pass. A pre-commit hook runs lint and test automatically.
+
+### 4. Open a PR
+
+- Target the `main` branch
+- Fill out the PR template — link the issue, describe what changed, check the impact areas
+- CI runs typecheck, lint, tests (Ubuntu + Windows), e2e, build, and Lighthouse
+
+## Commit Messages
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+TYPE(SCOPE): description
+```
+
+**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`, `build`, `revert`
+
+**Scopes:** `shared`, `web`, `cli`, `email-worker`, `ws-do`, `deps`, `config`
+
+Examples:
+
+```
+feat(web): add agent creation page
+fix(cli): resolve auth token refresh race condition
+chore(deps): update dependencies
+```
+
+Use the body to explain *what and why*, not how. Reference issues with `Closes #123`.
+
+## Testing
+
+- **Framework:** Vitest
+- **E2E:** Playwright (web package)
+- **Run all:** `pnpm test`
+- **Run by package:** `pnpm test:shared`, `pnpm test:cli`, `pnpm test:web`, `pnpm test:e2e`
+
+Tests run on both Ubuntu and Windows in CI.
+
+## Scripts Reference
+
+| Command | What it does |
+|---------|-------------|
+| `pnpm dev` | Start all dev servers (except CLI) |
+| `pnpm dev:web` | Next.js on :3000 |
+| `pnpm dev:cli` | CLI daemon |
+| `pnpm dev:email` | Email worker on :8788 |
+| `pnpm typecheck` | Typecheck all packages |
+| `pnpm lint` | Lint all packages |
+| `pnpm test` | Run all tests |
+| `pnpm db:migrate` | Run D1 migrations locally |
+| `pnpm db:reset` | Wipe local D1 and re-migrate |
+| `pnpm clean` | Remove node_modules, build artifacts, local D1 |
+
+## Reporting Issues
+
+Use [GitHub Issues](https://github.com/alookai/alook/issues). We have templates for:
+
+- **Bug reports** — reproduction steps, expected vs actual behavior
+- **Feature requests** — problem statement, proposed solution
+
+## Community
+
+- [Discord](https://discord.alook.ai) — questions, discussion, help
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [Apache-2.0 License](LICENSE).
diff --git a/README.md b/README.md
index 539c8cfeb..36dda6572 100644
--- a/README.md
+++ b/README.md
@@ -1,114 +1,92 @@
-# Alook
+<!-- TODO: Replace with Alook logo (recommended: 200px wide, centered) -->
-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.
+<p align="center">
+ <img src="" alt="Alook" width="200" />
+</p>
-## Architecture
+<h1 align="center">Alook</h1>
-```mermaid
-graph TD
- SMTP["Inbound Email (SMTP)"] --> EW
+<p align="center"><strong>Your Personal Company</strong></p>
- EW["Email Worker<br/><i>parse, store R2, create event</i>"]
- EW -- "service binding<br/>POST /api/email/notify" --> WS
+<p align="center">
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License" /></a>
+ <a href="https://github.com/alookai/alook/actions"><img src="https://github.com/alookai/alook/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+ <a href="https://discord.alook.ai"><img src="https://img.shields.io/badge/Discord-Join%20us-5865F2?logo=discord&logoColor=white" alt="Discord" /></a>
+</p>
- 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>"]
+<!-- TODO: Replace with hero screenshot — dashboard canvas view showing agent graph with connected agents, roles labeled -->
+<p align="center">
+ <img src="" alt="Alook Dashboard" width="700" />
+</p>
- WS -- "service binding" --> DO["WS-DO<br/><i>Browser-only real-time<br/>WebSocket channels</i>"]
-```
+---
+
+## What is Alook?
+
+Alook is the orchestration layer for your AI company. Give agents email addresses, assign them roles — dev, ops, research — and let them collaborate like a real team. Agents run on **your machine** with full access to your tools and codebase. Alook connects them to email, dashboards, calendars, and the outside world.
-### 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 (15s)<br/>- Event poll (3s)<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
+You're the CEO. Define the org chart. Your company runs 24/7.
+
+## Quick Start
+
+```bash
+npx @alook/app onboard
```
-## Services
+That's it. The onboard command walks you through setup — connecting your machine, detecting runtimes, and deploying your first agent.
-| 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 |
+## Features
-## Tech Stack
+**Collaboration** — Define roles, build your org chart. Agents coordinate automatically.
-- **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 Code, Codex, Opencode
-- **CLI Runtime:** Bun
-- **Monorepo:** Turborepo + pnpm workspaces
-- **Testing:** Vitest
+**Email-native** — Each agent gets its own `@alook.ai` email address. Send instructions, get replies.
-## Getting Started
+**Local-first** — Agents run on your machine. Your codebase never leaves.
-```bash
-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)
-```
+**Always-on** — A persistent daemon picks up tasks, responds to emails, and ships work while you sleep.
-## Development
+**Self-learning** — Agents build memory from past work — decisions, preferences, context. Your company gets sharper every day.
-```bash
-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
-```
+**Calendar** — Agents manage their own schedule. They know when to work, when to follow up, and when to wait.
-### Individual services
+**Traceable** — Every instruction, decision, and reply is recorded. Full accountability, no black boxes.
-```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
-```
+<!-- TODO: Replace with GIF — the core loop: agent receives email → task executes on local machine → result streams to dashboard in real-time -->
+
+<p align="center">
+ <img src="" alt="Alook workflow" width="700" />
+</p>
+
+## Bring Your Own Agent
+
+Alook is the orchestration layer. Pick the agents you trust — we give them roles, inboxes, and an always-on runtime.
+
+| Agent | Status |
+|-------|--------|
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Available |
+| [Codex](https://openai.com/index/introducing-codex/) | Available |
+| [OpenCode](https://github.com/opencode-ai/opencode) | Available |
+| Cursor | Coming Soon |
+| Hermes | Coming Soon |
+| OpenClaw | Coming Soon |
+
+## Templates
+
+Start with a pre-built company template — open-source maintainer, indie hacker ship crew, devops monitor, daily newsletter operator, and more.
+
+[Browse templates →](https://alook.ai/templates)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to get involved.
+
+## Community
-## Key Workflows
+- [Discord](https://discord.alook.ai) — Chat with the team and other builders
+- [Website](https://alook.ai) — Live product
-**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
+Built with Next.js, Cloudflare Workers, and Bun.
-**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
+## License
-**Runtime registration:** CLI `register <token>` -> detects local runtimes (claude, codex) -> registers with Web API -> starts daemon (polling)
+[Apache-2.0](LICENSE)
diff --git a/src/cli/daemon/prompt.ts b/src/cli/daemon/prompt.ts
index 0a5af601c..0df49d683 100644
--- a/src/cli/daemon/prompt.ts
+++ b/src/cli/daemon/prompt.ts
@@ -16,12 +16,12 @@ const ISSUE_NOTICE =
" Use `alook issue show --agent_id <your_agent_id> --issue_id <issue_id>` to read full context." +
" Use `alook issue update --agent_id <your_agent_id> --issue_id <issue_id> --status <status>` to change status." +
" Use `alook issue comment --agent_id <your_agent_id> --issue_id <issue_id> --body <text>` to leave a comment." +
- " CRITICAL — You MUST update the issue status before you finish. This is NOT optional:" +
+ " CRITICAL — You MUST manage the issue status correctly. This is NOT optional:" +
" 1. Set status to 'in_progress' when you start working." +
- " 2. Set status to 'review' as your LAST action before exiting — this means your work is done and ready for the owner to review. You cannot improve the issue further without user feedback." +
- " If you delegated work to colleagues, wait for their responses, then set 'review' once everything is complete." +
- " NEVER exit without updating the status. A task left in 'in_progress' is a failed task." +
- " Always leave a comment summarizing what you did before changing status to 'review'.";
+ " 2. If you complete the work yourself: leave a summary comment, then set status to 'review' as your last action. 'review' means there is actual completed work (code, artifact, result) ready for the owner to look at." +
+ " 3. If you delegated work to colleagues and are waiting for their response: KEEP status as 'in_progress' and exit. This is expected — you will be woken up when they reply. Set 'review' only after all delegated work is confirmed complete." +
+ " 4. NEVER set 'review' unless there is concrete completed work for the owner to review. Sending a plan to a colleague is NOT completed work." +
+ " NEVER exit without doing at least one of: updating the status, or leaving a comment explaining what you did and what you're waiting for.";
function buildDmNotice(name: string, email: string): string {
return (
diff --git a/src/web/src/components/agent-status-badge.tsx b/src/web/src/components/agent-status-badge.tsx
index cd6243481..7c3cc7853 100644
--- a/src/web/src/components/agent-status-badge.tsx
+++ b/src/web/src/components/agent-status-badge.tsx
@@ -105,11 +105,13 @@ export function AgentStatusBadge({ isOnline, taskCount, agentId }: AgentStatusBa
}
>
<StatusDot online />
- {taskCount > 0 && (
+ {taskCount > 0 ? (
<>
<span className="hidden sm:inline">Working</span>
<span className="tabular-nums">{taskCount}</span>
</>
+ ) : (
+ <span className="hidden sm:inline text-muted-foreground/40">Online</span>
)}
</PopoverTrigger>
<PopoverContent className="w-72 p-1">