docs: expand AGENTS.md with architecture, repo layout, and patterns guide

2026-08-05 06:24:37 +00:00 · 2026-01-27 20:54:15 +08:00
parent aef4da9ea9
commit 78fa9e7e4b
1 changed files with 123 additions and 21 deletions
@@ -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:<namespace>` suffix

 ## Critical Thinking