From 78fa9e7e4b71e71cb290927b840dcf08ee4ff828 Mon Sep 17 00:00:00 2001 From: weishu Date: Tue, 27 Jan 2026 20:54:15 +0800 Subject: [PATCH] docs: expand AGENTS.md with architecture, repo layout, and patterns guide --- AGENTS.md | 144 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 123 insertions(+), 21 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ad174cb1..c3092eaa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,37 +4,139 @@ Work style: telegraph; noun-phrases ok; drop grammar; Short guide for AI agents in this repo. Prefer progressive loading: start with the root README, then package READMEs as needed. +## What is HAPI? + +Local-first platform for running AI coding agents (Claude Code, Codex, Gemini) with remote control via web/phone. CLI wraps agents and connects to hub; hub serves web app and handles real-time sync. + ## Repo layout -- `cli/` - hapi CLI, runner, Codex/MCP tooling -- `hub/` - Telegram bot + HTTP API + Socket.IO + SSE -- `web/` - React Mini App / PWA + +``` +cli/ - CLI binary, agent wrappers, runner daemon +hub/ - HTTP API + Socket.IO + SSE + Telegram bot +web/ - React PWA for remote control +shared/ - Common types, schemas, utilities +docs/ - VitePress documentation site +website/ - Marketing site +``` + +Bun workspaces; `shared` consumed by cli, hub, web. + +## Architecture overview + +``` +┌─────────┐ Socket.IO ┌─────────┐ SSE/REST ┌─────────┐ +│ CLI │ ──────────── │ Hub │ ──────────── │ Web │ +│ (agent) │ │ (server)│ │ (PWA) │ +└─────────┘ └─────────┘ └─────────┘ + │ │ │ + ├─ Wraps Claude/Codex ├─ SQLite persistence ├─ TanStack Query + ├─ Socket.IO client ├─ Session cache ├─ SSE for updates + └─ RPC handlers ├─ RPC gateway └─ assistant-ui + └─ Telegram bot +``` + +**Data flow:** +1. CLI spawns agent (claude/codex/gemini), connects to hub via Socket.IO +2. Agent events → CLI → hub (socket `message` event) → DB + SSE broadcast +3. Web subscribes to SSE `/api/events`, receives live updates +4. User actions → Web → hub REST API → RPC to CLI → agent ## Reference docs -- `README.md` (user overview) -- `cli/README.md` (CLI behavior and config) -- `hub/README.md` (hub setup and architecture) -- `web/README.md` (web app behavior and dev workflow) -- `localdocs/` (optional deep dives) + +- `README.md` - User overview, quick start +- `cli/README.md` - CLI commands, config, runner +- `hub/README.md` - Hub config, HTTP API, Socket.IO events +- `web/README.md` - Routes, components, hooks +- `docs/guide/` - User guides (installation, how-it-works, FAQ) ## Shared rules -- No backward compatibility: breaking old format freely. -- TypeScript strict; no untyped code. -- Bun workspaces; run `bun` commands from repo root. -- Path alias `@/*` maps to `./src/*` per package. -- Prefer 4-space indentation. + +- No backward compatibility: breaking old formats freely +- TypeScript strict; no untyped code +- Bun workspaces; run `bun` commands from repo root +- Path alias `@/*` maps to `./src/*` per package +- Prefer 4-space indentation +- Zod for runtime validation (schemas in `shared/src/schemas.ts`) ## Common commands (repo root) -- `bun typecheck` -- `bun run test` +```bash +bun typecheck # All packages +bun run test # cli + hub tests +bun run dev # hub + web concurrently +bun run build:single-exe # All-in-one binary +``` ## Key source dirs -- `cli/src/api/`, `cli/src/claude/`, `cli/src/commands/`, `cli/src/codex/` -- `hub/src/web/`, `hub/src/socket/`, `hub/src/telegram/`, `hub/src/sync/` -- `hub/src/socket/handlers/cli/` - Terminal multiplexing, session handlers -- `hub/src/notifications/` - Push and Telegram notifications -- `web/src/components/`, `web/src/api/`, `web/src/hooks/` -- `web/src/routes/sessions/terminal.tsx` - Terminal UI + +### CLI (`cli/src/`) +- `api/` - Hub connection (Socket.IO client, auth) +- `claude/` - Claude Code integration (wrapper, hooks) +- `codex/` - Codex mode integration +- `agent/` - Multi-agent support (Gemini via ACP) +- `runner/` - Background daemon for remote spawn +- `commands/` - CLI subcommands (auth, runner, doctor) +- `modules/` - Tool implementations (ripgrep, difftastic, git) +- `ui/` - Terminal UI (Ink components) + +### Hub (`hub/src/`) +- `web/routes/` - REST API endpoints +- `socket/` - Socket.IO setup +- `socket/handlers/cli/` - CLI event handlers (session, terminal, machine, RPC) +- `sync/` - Core logic (sessionCache, messageService, rpcGateway) +- `store/` - SQLite persistence (better-sqlite3) +- `sse/` - Server-Sent Events manager +- `telegram/` - Bot commands, callbacks +- `notifications/` - Push (VAPID) and Telegram notifications +- `config/` - Settings loading, token generation +- `visibility/` - Client visibility tracking + +### Web (`web/src/`) +- `routes/` - TanStack Router pages +- `routes/sessions/` - Session views (chat, files, terminal) +- `components/` - Reusable UI (SessionList, SessionChat, NewSession/) +- `hooks/queries/` - TanStack Query hooks +- `hooks/mutations/` - Mutation hooks +- `hooks/useSSE.ts` - SSE subscription +- `api/client.ts` - API client wrapper + +### Shared (`shared/src/`) +- `types.ts` - Core types (Session, Message, Machine) +- `schemas.ts` - Zod schemas for validation +- `socket.ts` - Socket.IO event types +- `messages.ts` - Message parsing utilities +- `modes.ts` - Permission/model mode definitions + +## Testing + +- Test framework: Vitest (via `bun run test`) +- Test files: `*.test.ts` next to source +- Run: `bun run test` (from root) or `bun run test` (from package) +- Hub tests: `hub/src/**/*.test.ts` +- CLI tests: `cli/src/**/*.test.ts` +- No web tests currently + +## Common tasks + +| Task | Key files | +|------|-----------| +| Add CLI command | `cli/src/commands/`, `cli/src/index.ts` | +| Add API endpoint | `hub/src/web/routes/`, register in `hub/src/web/index.ts` | +| Add Socket.IO event | `hub/src/socket/handlers/cli/`, `shared/src/socket.ts` | +| Add web route | `web/src/routes/`, `web/src/router.tsx` | +| Add web component | `web/src/components/` | +| Modify session logic | `hub/src/sync/sessionCache.ts`, `hub/src/sync/syncEngine.ts` | +| Modify message handling | `hub/src/sync/messageService.ts` | +| Add notification type | `hub/src/notifications/` | +| Add shared type | `shared/src/types.ts`, `shared/src/schemas.ts` | + +## Important patterns + +- **RPC**: CLI registers handlers (`rpc-register`), hub routes requests via `rpcGateway.ts` +- **Versioned updates**: CLI sends `update-metadata`/`update-state` with version; hub rejects stale +- **Session modes**: `local` (terminal) vs `remote` (web-controlled); switchable mid-session +- **Permission modes**: `default`, `acceptEdits`, `bypassPermissions`, `plan` +- **Namespaces**: Multi-user isolation via `CLI_API_TOKEN:` suffix ## Critical Thinking