wushenghua/hapi
1
0
Fork 0
mirror of https://github.com/wu736139669/hapi.git synced 2026-08-05 06:24:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update all README files with comprehensive documentation

Browse Source 
Update documentation across the project to reflect current state of codebase:
- cli/README.md: Add all commands (codex, gemini, daemon subcommands, doctor, mcp),
  configuration options, storage locations, and source structure references
- server/README.md: Add complete HTTP API reference, Socket.IO events, Telegram bot
  features, core logic descriptions, and source structure
- web/README.md: Add all routes, feature descriptions, authentication flow, data
  fetching, real-time updates, and source structure
- README.md: Improve feature list clarity, add HTTPS exposure instructions in
  quickstart, add multi-agent support section
This commit is contained in:
weishu
2025-12-24 17:56:07 +08:00
parent 852c7f4c4e
commit eee4489b0f
4 changed files with 387 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+55 -22
View File
@@ -2,30 +2,30 @@
HAPI means "哈皮," a Chinese transliteration of [happy](https://github.com/slopus/happy), great credit to the original Happy project.
Run Claude Code / Codex / Coding Agent sessions locally and control them remotely through a Web / PWA / Telegram mini App.
Run Claude Code / Codex / Gemini sessions locally and control them remotely through a Web / PWA / Telegram Mini App.
## Features
- Start AI coding sessions from any machine.
- Monitor and control sessions from your phone or browser.
- Approve or deny tool permissions remotely.
- Browse files and view git diffs.
- Track session progress with todo lists.
- Supports multiple AI backends: Claude Code, Codex, and Gemini.
## Quickstart (single executable)
1. Download the prebuilt `hapi` binary for your platform and put it on your PATH.
2. Start the server on a machine you control: `hapi server`
Optional for telegram, add a `.env` file and then start server:
2. Start the server on a machine you control:
```bash
hapi server
```
WEBAPP_URL="https://your-domain.example" # required for Telegram Mini App
TELEGRAM_BOT_TOKEN="..."
ALLOWED_CHAT_IDS="12345678"
```
If you only want the web app + CLI, you can skip these vars.
To enable Telegram later, set TELEGRAM_BOT_TOKEN and WEBAPP_URL, start the server, send `/start`
to the bot to get your chat ID, set ALLOWED_CHAT_IDS, and restart the server.
3. If the server has no public IP, expose it over HTTPS:
- Cloudflare Tunnel docs: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/
- Tailscale docs: https://tailscale.com/kb/
- Telegram Mini Apps require HTTPS.
- Cloudflare Tunnel: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/
- Tailscale: https://tailscale.com/kb/
4. Run the CLI on the machine where you want sessions:
@@ -36,34 +36,67 @@ export HAPI_BOT_URL="https://your-domain.example"
hapi
```
5. Open the UI:
- In Telegram, run `/app` in the bot chat.
- In a browser, open `WEBAPP_URL` and log in with `CLI_API_TOKEN`.
5. Open the UI in a browser at the server URL and log in with `CLI_API_TOKEN`.
## Telegram Mini App (optional)
To use Telegram for notifications and the Mini App:
1. Create a bot with @BotFather and get the token.
2. Expose your server over HTTPS (Cloudflare Tunnel, Tailscale, etc.).
3. Add environment variables:
```
WEBAPP_URL="https://your-domain.example"
TELEGRAM_BOT_TOKEN="..."
```
4. Start the server and send `/start` to the bot to get your chat ID.
5. Add your chat ID and restart:
```
ALLOWED_CHAT_IDS="12345678"
```
6. Run `/app` in the bot chat to open the Mini App.
## Multi-agent support
- `hapi` - Start a Claude Code session.
- `hapi codex` - Start an OpenAI Codex session.
- `hapi gemini` - Start a Google Gemini session.
## CLI config file
You can store the token in `~/.hapi/settings.json` instead of an env var.
Environment variables take priority over the file.
## Requirements
- Claude CLI installed and logged in (`claude` on PATH).
- A Telegram bot token from @BotFather (for Mini App access).
- Claude CLI installed and logged in (`claude` on PATH) for Claude Code sessions.
- Bun if building from source.
## Build from source
```bash
bun install
bun run build
```
Build a single binary with embedded web assets:
```bash
bun run build:single-exe
```
## Docs
- `cli/README.md` - CLI usage and config
- `server/README.md` - server setup and architecture
- `web/README.md` - web app behavior and dev workflow
- `server/README.md` - Server setup and architecture
- `web/README.md` - Web app behavior and dev workflow
## License
cli/README.md
+89 -25
View File
@@ -1,56 +1,107 @@
# hapi CLI
Run Claude Code or Codex sessions from your terminal and control them remotely through the hapi server.
Run Claude Code, Codex, or Gemini sessions from your terminal and control them remotely through the hapi server.
## What it does
- Starts Claude Code sessions and registers them with hapi-server.
- Starts Codex mode for OpenAI-based sessions.
- Starts Gemini mode via ACP (Anthropic Code Plugins).
- Provides an MCP stdio bridge for external tools.
- Manages a background daemon for long-running sessions.
- Includes diagnostics and auth helpers.
## Typical flow
1. Start the server and set env vars (see ../server/README.md).
2. Set the same CLI_API_TOKEN on this machine or run `hapi auth login`.
3. Run `hapi` to start a session.
4. Use the web app or Telegram Mini App to monitor and control.
## Quickstart
```bash
# Point to the server if it is not on localhost:3006
export HAPI_BOT_URL="https://your-server-domain"
hapi # prompts for CLI_API_TOKEN and saves it locally
```
## Commands
- `hapi` - start a Claude Code session (passes through Claude CLI flags)
- `hapi codex` - start Codex mode
- `hapi mcp` - start MCP stdio bridge
- `hapi auth` - login/status/logout for CLI_API_TOKEN
- `hapi server` - start the bundled server (single binary workflow)
- `hapi daemon` - manage background service
- `hapi doctor` - diagnostics and cleanup
### Session commands
- `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 gemini` - Start Gemini mode via ACP. See `src/agent/runners/runAgentSession.ts`.
### Authentication
- `hapi auth status` - Show authentication configuration and token source.
- `hapi auth login` - Interactively enter and save CLI_API_TOKEN.
- `hapi auth logout` - Clear saved credentials.
See `src/commands/auth.ts`.
### Daemon management
- `hapi daemon start` - Start daemon as detached process.
- `hapi daemon stop` - Stop daemon gracefully.
- `hapi daemon status` - Show daemon diagnostics.
- `hapi daemon list` - List active sessions managed by daemon.
- `hapi daemon stop-session <sessionId>` - Terminate specific session.
- `hapi daemon logs` - Print path to latest daemon log file.
- `hapi daemon install` - Install daemon as system service.
- `hapi daemon uninstall` - Remove daemon system service.
See `src/daemon/run.ts`.
### Diagnostics
- `hapi doctor` - Show full diagnostics (version, daemon status, logs, processes).
- `hapi doctor clean` - Kill runaway HAPI processes.
See `src/ui/doctor.ts`.
### Other
- `hapi mcp` - Start MCP stdio bridge. See `src/codex/happyMcpStdioBridge.ts`.
- `hapi server` - Start the bundled server (single binary workflow).
## Configuration
Required:
- `CLI_API_TOKEN` - shared secret; must match the server
- `HAPI_BOT_URL` - server base URL (default: http://localhost:3006)
`CLI_API_TOKEN` can be set via env or stored in `~/.hapi/settings.json` (env wins).
See `src/configuration.ts` for all options.
Optional:
- `HAPI_HOME` - config/data directory (default: ~/.hapi)
- `HAPI_EXPERIMENTAL` - enable experimental features (true/1/yes)
- `HAPI_HTTP_MCP_URL` - default MCP target for `hapi mcp`
- `HAPI_CLAUDE_PATH` - path to a specific `claude` executable
### Required
- `CLI_API_TOKEN` - Shared secret; must match the server. Can be set via env or `~/.hapi/settings.json` (env wins).
- `HAPI_BOT_URL` - Server base URL (default: http://localhost:3006).
### Optional
- `HAPI_HOME` - Config/data directory (default: ~/.hapi).
- `HAPI_EXPERIMENTAL` - Enable experimental features (true/1/yes).
- `HAPI_CLAUDE_PATH` - Path to a specific `claude` executable.
- `HAPI_HTTP_MCP_URL` - Default MCP target for `hapi mcp`.
### Daemon
- `HAPI_DAEMON_HEARTBEAT_INTERVAL` - Heartbeat interval in ms (default: 60000).
- `HAPI_DAEMON_HTTP_TIMEOUT` - HTTP timeout for daemon control in ms (default: 10000).
### Gemini/Agent
- `HAPPY_GEMINI_COMMAND` - Gemini executable command (default: gemini).
- `HAPPY_GEMINI_ARGS` - Gemini arguments (default: --acp).
## Storage
Data is stored in `~/.hapi/` (or `$HAPI_HOME`):
- `settings.json` - User settings (machineId, token, onboarding flag). See `src/persistence.ts`.
- `daemon.state.json` - Daemon state (pid, port, version, heartbeat).
- `logs/` - Log files.
## Requirements
- Claude CLI installed and logged in (`claude` on PATH).
- Bun for building from source.
## Build from source
From the repo root:
```bash
bun install
bun run build:cli
@@ -58,10 +109,23 @@ bun run build:cli:exe
```
For an all-in-one binary that also embeds the web app:
```bash
bun run build:single-exe
```
## Source structure
- `src/api/` - Bot communication (Socket.IO + REST).
- `src/claude/` - Claude Code integration.
- `src/codex/` - Codex mode integration.
- `src/agent/` - Multi-agent support (Gemini via ACP).
- `src/daemon/` - Background service.
- `src/commands/` - CLI command handlers.
- `src/ui/` - User interface and diagnostics.
- `src/modules/` - Tool implementations (ripgrep, difftastic, git).
## Related docs
- `../server/README.md`
- `../web/README.md`
server/README.md
+152 -30
View File
@@ -3,6 +3,7 @@
Telegram bot + HTTP API + realtime updates for hapi.
## What it does
- Telegram bot for notifications and the Mini App entrypoint.
- HTTP API for sessions, messages, permissions, machines, and files.
- Server-Sent Events stream for live updates in the web app.
@@ -10,29 +11,31 @@ Telegram bot + HTTP API + realtime updates for hapi.
- Serves the web app from `web/dist` or embedded assets in the single binary.
- Persists state in SQLite.
## Typical deployment flow
1. Configure env vars.
2. Expose the server to the internet (HTTPS) if you need Telegram Mini App access.
3. Run the server.
4. Point the CLI to the server and open the web app.
## Configuration
Required:
- `CLI_API_TOKEN` - shared secret used by CLI and web login.
Optional (Telegram):
- `TELEGRAM_BOT_TOKEN` - token from @BotFather.
- `ALLOWED_CHAT_IDS` - comma-separated chat IDs allowed to use the bot.
- `WEBAPP_URL` - public HTTPS URL for Telegram Mini App access.
See `src/configuration.ts` for all options.
### Required
- `CLI_API_TOKEN` - Shared secret used by CLI and web login. Auto-generated if not set.
### Optional (Telegram)
- `TELEGRAM_BOT_TOKEN` - Token from @BotFather.
- `ALLOWED_CHAT_IDS` - Comma-separated chat IDs allowed to use the bot.
- `WEBAPP_URL` - Public HTTPS URL for Telegram Mini App access.
### Optional
Optional:
- `WEBAPP_PORT` - HTTP port (default: 3006).
- `CORS_ORIGINS` - comma-separated origins, or `*`.
- `HAPI_HOME` - data directory (default: ~/.hapi).
- `DB_PATH` - SQLite database path.
- `CORS_ORIGINS` - Comma-separated origins, or `*`.
- `HAPI_HOME` - Data directory (default: ~/.hapi).
- `DB_PATH` - SQLite database path (default: HAPI_HOME/hapi.db).
## Running
Binary (single executable):
```bash
export TELEGRAM_BOT_TOKEN="..."
export ALLOWED_CHAT_IDS="12345678"
@@ -47,18 +50,146 @@ To enable Telegram, set TELEGRAM_BOT_TOKEN and WEBAPP_URL, start the server, sen
to the bot to get your chat ID, set ALLOWED_CHAT_IDS, and restart the server.
From source:
```bash
bun install
bun run dev:server
```
Or inside `server/`:
```bash
bun run start
```
## HTTP API
See `src/web/routes/` for all endpoints.
### Authentication (`src/web/routes/auth.ts`)
- `POST /api/auth` - Get JWT token (Telegram initData or CLI_API_TOKEN).
### Sessions (`src/web/routes/sessions.ts`)
- `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/permission-mode` - Set permission mode.
- `POST /api/sessions/:id/model` - Set model preference.
### Messages (`src/web/routes/messages.ts`)
- `GET /api/sessions/:id/messages` - Get messages (paginated).
- `POST /api/sessions/:id/messages` - Send message.
### Permissions (`src/web/routes/permissions.ts`)
- `POST /api/sessions/:id/permissions/:requestId/approve` - Approve permission.
- `POST /api/sessions/:id/permissions/:requestId/deny` - Deny permission.
### Machines (`src/web/routes/machines.ts`)
- `GET /api/machines` - List online machines.
- `POST /api/machines/:id/spawn` - Spawn new session on machine.
### Git/Files (`src/web/routes/git.ts`)
- `GET /api/sessions/:id/git-status` - Git status.
- `GET /api/sessions/:id/git-diff-numstat` - Diff summary.
- `GET /api/sessions/:id/git-diff-file` - File-specific diff.
- `GET /api/sessions/:id/file` - Read file content.
- `GET /api/sessions/:id/files` - File search with ripgrep.
### Events (`src/web/routes/events.ts`)
- `GET /api/events` - SSE stream for live updates.
### CLI (`src/web/routes/cli.ts`)
- `POST /cli/sessions` - Create/load session.
- `GET /cli/sessions/:id` - Get session by ID.
- `POST /cli/machines` - Create/load machine.
- `GET /cli/machines/:id` - Get machine by ID.
## Socket.IO
See `src/socket/handlers/cli.ts` for event handlers.
Namespace: `/cli`
### Client events (CLI to server)
- `message` - Send message to session.
- `update-metadata` - Update session metadata.
- `update-state` - Update agent state.
- `session-alive` - Keep session active.
- `session-end` - Mark session ended.
- `machine-alive` - Keep machine online.
- `rpc-register` - Register RPC handler.
- `rpc-unregister` - Unregister RPC handler.
### Server events (server to clients)
- `update` - Broadcast session/message updates.
- `rpc-request` - Incoming RPC call.
See `src/socket/rpcRegistry.ts` for RPC routing.
## Telegram Bot
See `src/telegram/bot.ts` for bot implementation.
### Commands
- `/start` - Welcome message with chat ID.
- `/app` - Open Mini App.
### Features
- Permission request notifications with approve/deny buttons.
- Session ready notifications.
- Deep links to Mini App sessions.
See `src/telegram/callbacks.ts` for button handlers.
## Core Logic
See `src/sync/syncEngine.ts` for the main session/message manager:
- In-memory session cache with versioning.
- Message pagination and retrieval.
- Permission approval/denial.
- RPC method routing via Socket.IO.
- Event publishing to SSE and Telegram.
- Git operations and file search.
- Activity tracking and timeouts.
## Storage
See `src/store/index.ts` for SQLite persistence:
- Sessions with metadata and agent state.
- Messages with pagination support.
- Machines with daemon state.
- Todo extraction from messages.
## Source structure
- `src/web/` - HTTP server and routes.
- `src/socket/` - Socket.IO setup and handlers.
- `src/telegram/` - Telegram bot.
- `src/sync/` - Core session/message logic.
- `src/store/` - SQLite persistence.
- `src/sse/` - Server-Sent Events.
## Security model
Access is controlled by:
- Telegram chat ID allowlist (when Telegram is enabled).
- `CLI_API_TOKEN` shared secret for CLI and browser access.
Transport security depends on HTTPS in front of the server.
## Build for deployment
From the repo root:
```bash
bun run build:server
bun run build:web
@@ -67,15 +198,6 @@ bun run build:web
The server build output is `server/dist/index.js`, and the web assets are in `web/dist`.
## Networking notes
- Telegram Mini Apps require HTTPS and a public URL. If the server has no public IP, use Cloudflare Tunnel or Tailscale and set `WEBAPP_URL` to the HTTPS endpoint.
- If the web app is hosted on a different origin, set `CORS_ORIGINS` accordingly.
## Architecture overview
The server is the hub for direct-connect mode. It accepts CLI connections over Socket.IO, exposes HTTP endpoints for the web UI, and publishes live updates over SSE. A Telegram bot provides notifications and a Mini App entrypoint. Session and machine state are stored in a local SQLite database.
## Security model
Access is controlled by:
- Telegram chat ID allowlist (when Telegram is enabled).
- `CLI_API_TOKEN` shared secret for CLI and browser access.
Transport security depends on HTTPS in front of the server.
web/README.md
+91 -4
View File
@@ -3,20 +3,109 @@
React Mini App / PWA for monitoring and controlling hapi sessions.
## What it does
- Session list with status, pending approvals, and summaries.
- Session list with status, pending approvals, todos, and summaries.
- Chat view with streaming updates and message sending.
- Permission approval and denial workflows.
- Permission mode and model selection.
- Machine list and remote session spawn.
- File browser and git status/diff views.
- PWA install prompt and offline banner.
## Runtime behavior
- When opened inside Telegram, auth uses Telegram WebApp init data.
- When opened in a normal browser, you can log in with the shared `CLI_API_TOKEN`.
- Live updates come from the server via SSE.
## Routes
See `src/router.tsx` for route definitions.
- `/` - Redirect to /sessions.
- `/sessions` - Session list.
- `/sessions/$sessionId` - Chat interface.
- `/sessions/new` - Create new session.
- `/sessions/$sessionId/files` - File browser with git status.
- `/sessions/$sessionId/file` - File viewer with diff support.
## Features
### Session list (`src/components/SessionList.tsx`)
- Active/inactive status indicator.
- Session title from name, summary, or path.
- Todo progress display.
- Pending permission request count.
- Agent flavor label (claude/codex/gemini).
- Model mode display.
### Chat interface (`src/components/SessionChat.tsx`)
- Message thread with infinite scroll.
- Composer for sending messages.
- Permission mode toggle (default/acceptEdits/bypassPermissions/plan).
- Model selection (default/sonnet/opus).
- Session abort and mode switch controls.
- Context size display.
### File browser (`src/routes/sessions/files.tsx`)
- Git status view (staged/unstaged files).
- File search with ripgrep.
- Navigate to file viewer.
### File viewer (`src/routes/sessions/file.tsx`)
- File content display with syntax highlighting.
- Staged/unstaged diff view.
### New session (`src/components/NewSession.tsx`)
- Machine selector.
- Directory input with recent paths.
- Agent type selector (claude/codex/gemini).
## Authentication
See `src/hooks/useAuth.ts` and `src/hooks/useAuthSource.ts`.
- Telegram Mini App: Uses initData from WebApp SDK.
- Browser: Uses CLI_API_TOKEN from login prompt.
- JWT tokens with auto-refresh.
## Data fetching
See `src/hooks/queries/` for query hooks and `src/hooks/mutations/` for mutations.
- Sessions, messages, machines via TanStack Query.
- Git status and file operations.
- Optimistic updates for message sending.
## Real-time updates
See `src/hooks/useSSE.ts`.
- SSE connection to `/api/events`.
- Session/message/machine update events.
- Automatic cache invalidation on events.
## Stack
React 19 + Vite + TanStack Router/Query + Tailwind + @assistant-ui/react.
## Source structure
- `src/router.tsx` - Route definitions.
- `src/components/` - UI components.
- `src/hooks/` - Data fetching and state hooks.
- `src/api/client.ts` - API client.
- `src/types/api.ts` - Type definitions.
## Development
From the repo root:
```bash
bun install
bun run dev:web
@@ -27,11 +116,9 @@ If testing in Telegram, set:
- `CORS_ORIGINS` to include the dev server origin.
## Build
```bash
bun run build:web
```
The built assets land in `web/dist` and are served by hapi-server. The single executable can embed these assets.
## Stack
React 19 + Vite + TanStack Router/Query + Tailwind.