diff --git a/AGENTS.md b/AGENTS.md index 0975a023..ad174cb1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,7 +31,10 @@ Short guide for AI agents in this repo. Prefer progressive loading: start with t ## 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 ## Critical Thinking diff --git a/cli/README.md b/cli/README.md index dfd86966..d1f5b833 100644 --- a/cli/README.md +++ b/cli/README.md @@ -24,6 +24,7 @@ Run Claude Code, Codex, or Gemini sessions from your terminal and control them r - `hapi` - Start a Claude Code session (passes through Claude CLI flags). See `src/index.ts`. - `hapi codex` - Start Codex mode. See `src/codex/runCodex.ts`. +- `hapi codex resume ` - Resume existing Codex session. - `hapi gemini` - Start Gemini mode via ACP. See `src/agent/runners/runAgentSession.ts`. Note: Gemini runs in remote mode only; it waits for messages from the hub UI/Telegram. @@ -43,8 +44,6 @@ See `src/commands/auth.ts`. - `hapi runner list` - List active sessions managed by runner. - `hapi runner stop-session ` - Terminate specific session. - `hapi runner logs` - Print path to latest runner log file. -- `hapi runner install` - Install runner as system service. -- `hapi runner uninstall` - Remove runner system service. See `src/runner/run.ts`. @@ -82,6 +81,14 @@ See `src/configuration.ts` for all options. - `HAPI_RUNNER_HEARTBEAT_INTERVAL` - Heartbeat interval in ms (default: 60000). - `HAPI_RUNNER_HTTP_TIMEOUT` - HTTP timeout for runner control in ms (default: 10000). +### Worktree (set by runner) + +- `HAPI_WORKTREE_BASE_PATH` - Base repository path. +- `HAPI_WORKTREE_BRANCH` - Current branch name. +- `HAPI_WORKTREE_NAME` - Worktree name. +- `HAPI_WORKTREE_PATH` - Full worktree path. +- `HAPI_WORKTREE_CREATED_AT` - Creation timestamp (ms). + ## Storage Data is stored in `~/.hapi/` (or `$HAPI_HOME`): diff --git a/docs/guide/faq.md b/docs/guide/faq.md index 47ede8c9..f9396b80 100644 --- a/docs/guide/faq.md +++ b/docs/guide/faq.md @@ -91,6 +91,10 @@ In the session view, tap the "Files" tab to: Yes. Open any session and use the chat interface to send messages directly to the AI agent. +### Can I access a terminal remotely? + +Yes. Open a session in the web app and tap the Terminal tab for a remote shell. + ### How do I use voice control? Set `ELEVENLABS_API_KEY`, open a session in the web app, and click the microphone button. See [Voice Assistant](./voice-assistant.md). diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md index 40930b39..4018ec6e 100644 --- a/docs/guide/quick-start.md +++ b/docs/guide/quick-start.md @@ -55,6 +55,6 @@ Enter your access token to log in. ## Next steps - [Seamless Handoff](./how-it-works.md#seamless-handoff) - Switch between terminal and phone seamlessly -- [Remote access](./installation.md#remote-access) - Access HAPI from anywhere +- [Hub setup](./installation.md#hub-setup) - Access HAPI from anywhere - [Notifications](./installation.md#telegram-setup) - Set up Telegram notifications - [Install the App](./pwa.md) - Add HAPI to your home screen diff --git a/hub/README.md b/hub/README.md index cb138aa8..24119c09 100644 --- a/hub/README.md +++ b/hub/README.md @@ -17,7 +17,7 @@ See `src/configuration.ts` for all options. ### Required -- `CLI_API_TOKEN` - Base shared secret used by CLI and web login. Clients append `:` for isolation. +- `CLI_API_TOKEN` - Base shared secret used by CLI and web login. Clients append `:` for isolation. Auto-generated on first run if not set. ### Optional (Telegram) @@ -36,6 +36,11 @@ See `src/configuration.ts` for all options. - `CORS_ORIGINS` - Comma-separated origins, or `*`. - `HAPI_HOME` - Data directory (default: ~/.hapi). - `DB_PATH` - SQLite database path (default: HAPI_HOME/hapi.db). +- `TELEGRAM_NOTIFICATION` - Enable/disable Telegram notifications (default: true). +- `HAPI_RELAY_API` - Relay API domain (default: relay.hapi.run). +- `HAPI_RELAY_AUTH` - Relay auth key (default: hapi). +- `HAPI_RELAY_FORCE_TCP` - Force TCP relay mode (true/1). +- `VAPID_SUBJECT` - Contact email/URL for Web Push. ## Running @@ -76,7 +81,15 @@ See `src/web/routes/` for all endpoints. - `GET /api/sessions` - List all sessions. - `GET /api/sessions/:id` - Get session details. - `POST /api/sessions/:id/abort` - Abort session. -- `POST /api/sessions/:id/switch` - Switch session mode (remote/local). +- `POST /api/sessions/:id/switch` - Switch session to remote mode. +- `POST /api/sessions/:id/resume` - Resume inactive session. +- `POST /api/sessions/:id/upload` - Upload file (base64, max 50MB). +- `POST /api/sessions/:id/upload/delete` - Delete uploaded file. +- `POST /api/sessions/:id/archive` - Archive active session. +- `PATCH /api/sessions/:id` - Rename session. +- `DELETE /api/sessions/:id` - Delete inactive session. +- `GET /api/sessions/:id/slash-commands` - List slash commands. +- `GET /api/sessions/:id/skills` - List skills. - `POST /api/sessions/:id/permission-mode` - Set permission mode. - `POST /api/sessions/:id/model` - Set model preference. @@ -94,6 +107,7 @@ See `src/web/routes/` for all endpoints. - `GET /api/machines` - List online machines. - `POST /api/machines/:id/spawn` - Spawn new session on machine. +- `POST /api/machines/:id/paths/exists` - Check if path exists. ### Git/Files (`src/web/routes/git.ts`) @@ -106,11 +120,18 @@ See `src/web/routes/` for all endpoints. ### Events (`src/web/routes/events.ts`) - `GET /api/events` - SSE stream for live updates. +- `POST /api/visibility` - Report client visibility state. ### Voice (`src/web/routes/voice.ts`) - `POST /api/voice/token` - Get ElevenLabs conversation token. +### Push Notifications (`src/web/routes/push.ts`) + +- `GET /api/push/vapid-public-key` - Get VAPID public key. +- `POST /api/push/subscribe` - Subscribe to push notifications. +- `DELETE /api/push/subscribe` - Unsubscribe. + ### CLI (`src/web/routes/cli.ts`) - `POST /cli/sessions` - Create/load session. @@ -135,6 +156,13 @@ Namespace: `/cli` - `rpc-register` - Register RPC handler. - `rpc-unregister` - Unregister RPC handler. +### Terminal events (web to hub) + +- `terminal:create` - Open terminal for session. +- `terminal:write` - Send input. +- `terminal:resize` - Resize dimensions. +- `terminal:close` - Close terminal. + ### Hub events (hub to clients) - `update` - Broadcast session/message updates. @@ -185,10 +213,14 @@ See `src/store/index.ts` for SQLite persistence: - `src/web/` - HTTP service and routes. - `src/socket/` - Socket.IO setup and handlers. +- `src/socket/handlers/cli/` - Modular CLI handlers. - `src/telegram/` - Telegram bot. - `src/sync/` - Core session/message logic. - `src/store/` - SQLite persistence. - `src/sse/` - Server-Sent Events. +- `src/config/` - Configuration loading and generation. +- `src/notifications/` - Push and Telegram notifications. +- `src/visibility/` - Client visibility tracking. ## Security model diff --git a/web/README.md b/web/README.md index 23197489..199a0913 100644 --- a/web/README.md +++ b/web/README.md @@ -29,6 +29,8 @@ See `src/router.tsx` for route definitions. - `/sessions/new` - Create new session. - `/sessions/$sessionId/files` - File browser with git status. - `/sessions/$sessionId/file` - File viewer with diff support. +- `/sessions/$sessionId/terminal` - Terminal interface. +- `/settings` - Application settings. ## Features @@ -61,11 +63,25 @@ See `src/router.tsx` for route definitions. - File content display with syntax highlighting. - Staged/unstaged diff view. -### New session (`src/components/NewSession.tsx`) +### Terminal (`src/routes/sessions/terminal.tsx`) -- Machine selector. -- Directory input with recent paths. -- Agent type selector (claude/codex/gemini). +- Remote terminal via xterm.js +- Real-time via Socket.IO +- Resize handling + +### Voice assistant + +- ElevenLabs integration (@elevenlabs/react) +- Real-time voice control + +### New session (`src/components/NewSession/`) + +Modular session creation: +- Machine selector +- Directory input with recent paths +- Agent type selector +- Model selector +- Permission mode toggle (YOLO mode) ## Authentication @@ -93,7 +109,7 @@ See `src/hooks/useSSE.ts`. ## Stack -React 19 + Vite + TanStack Router/Query + Tailwind + @assistant-ui/react. +React 19 + Vite + TanStack Router/Query + Tailwind + @assistant-ui/react + xterm.js + @elevenlabs/react + socket.io-client + workbox + shiki. ## Source structure