Skip to content

AGENTS.md

Latest commit

 

History

History
148 lines (119 loc) · 5.88 KB

AGENTS.md

File metadata and controls

148 lines (119 loc) · 5.88 KB

AGENTS.md

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/     - 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, 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 formats freely
  • Prioritize Pragmatism, and Avoid Overengineering.
  • Write necessary tests ONLY.
  • 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           # 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 (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

  1. Fix root cause (not band-aid).
  2. Unsure: read more code; if still stuck, ask w/ short options.
  3. Conflicts: call out; pick safer path.
  4. Unrecognized changes: assume other agent; keep going; focus your changes. If it causes issues, stop + ask user.