mirror of
https://github.com/wu736139669/hapi.git
synced 2026-08-05 06:24:37 +00:00
Mao MrandGitHub
c9be2894ac
* feat(cursor): add support for Cursor Agent CLI integration - Introduced new command `hapi cursor` to start Cursor Agent sessions. - Added functionality for resuming sessions and managing permission modes. - Updated documentation to include Cursor Agent usage and installation instructions. - Enhanced existing codebase to accommodate Cursor as a recognized agent flavor. - Implemented local and remote session handling for Cursor Agent. This update expands HAPI's capabilities by integrating support for the Cursor Agent, allowing users to leverage its features alongside existing agents. * Remove TODO.md file as it is no longer needed following the integration of Cursor Agent CLI support. This cleanup helps streamline project documentation and reflects the completion of the associated tasks. * feat(cursor): implement remote mode and fix --hapi-starting-mode - Consume --hapi-starting-mode in cursor command (do not forward to agent) - Implement cursorRemoteLauncher: spawn agent -p with stream-json, --trust - Add cursorEventConverter for NDJSON parsing (system/assistant/tool_call/result) - Multi-turn via --resume session_id - Update docs: cursor supports both local and remote modes Made-with: Cursor * fix: type error * fix(cursor): address PR review - model UI, sessionId metadata, duplicate flags - HappyComposer: use isClaudeFlavor for model mode (cursor has no model modes) - cursorLocalLauncher: call onSessionFound for resume so cursorSessionId in metadata - cursorCommand: do not forward parsed flags to cursorArgs (avoid duplicates) Made-with: Cursor
147 lines
4.9 KiB
Markdown
147 lines
4.9 KiB
Markdown
# hapi CLI
|
|
|
|
Run Claude Code, Codex, Cursor Agent, Gemini, or OpenCode sessions from your terminal and control them remotely through the hapi hub.
|
|
|
|
## What it does
|
|
|
|
- Starts Claude Code sessions and registers them with hapi-hub.
|
|
- Starts Codex mode for OpenAI-based sessions.
|
|
- Starts Cursor Agent mode for Cursor CLI sessions.
|
|
- Starts Gemini mode via ACP (Anthropic Code Plugins).
|
|
- Starts OpenCode mode via ACP and its plugin hook system.
|
|
- Provides an MCP stdio bridge for external tools.
|
|
- Manages a background runner for long-running sessions.
|
|
- Includes diagnostics and auth helpers.
|
|
|
|
## Typical flow
|
|
|
|
1. Start the hub and set env vars (see ../hub/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.
|
|
|
|
## Commands
|
|
|
|
### 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 codex resume <sessionId>` - Resume existing Codex session.
|
|
- `hapi cursor` - Start Cursor Agent mode. See `src/cursor/runCursor.ts`.
|
|
Supports `hapi cursor resume <chatId>`, `hapi cursor --continue`, `--mode plan|ask`, `--yolo`, `--model`.
|
|
Local and remote modes supported; remote uses `agent -p` with stream-json.
|
|
- `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.
|
|
- `hapi opencode` - Start OpenCode mode via ACP. See `src/opencode/runOpencode.ts`.
|
|
Note: OpenCode supports local and remote modes; local mode streams via OpenCode plugins.
|
|
|
|
### 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`.
|
|
|
|
### Runner management
|
|
|
|
- `hapi runner start` - Start runner as detached process.
|
|
- `hapi runner stop` - Stop runner gracefully.
|
|
- `hapi runner status` - Show runner diagnostics.
|
|
- `hapi runner list` - List active sessions managed by runner.
|
|
- `hapi runner stop-session <sessionId>` - Terminate specific session.
|
|
- `hapi runner logs` - Print path to latest runner log file.
|
|
|
|
See `src/runner/run.ts`.
|
|
|
|
### Diagnostics
|
|
|
|
- `hapi doctor` - Show full diagnostics (version, runner 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 hub` - Start the bundled hub (single binary workflow).
|
|
- `hapi server` - Alias for `hapi hub`.
|
|
|
|
## Configuration
|
|
|
|
See `src/configuration.ts` for all options.
|
|
|
|
### Required
|
|
|
|
- `CLI_API_TOKEN` - Shared secret; must match the hub. Can be set via env or `~/.hapi/settings.json` (env wins).
|
|
- `HAPI_API_URL` - Hub 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`.
|
|
|
|
### Runner
|
|
|
|
- `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`):
|
|
|
|
- `settings.json` - User settings (machineId, token, onboarding flag). See `src/persistence.ts`.
|
|
- `runner.state.json` - Runner state (pid, port, version, heartbeat).
|
|
- `logs/` - Log files.
|
|
|
|
## Requirements
|
|
|
|
- Claude CLI installed and logged in (`claude` on PATH).
|
|
- Cursor Agent CLI installed (`agent` on PATH) for `hapi cursor`. Install: `curl https://cursor.com/install -fsS | bash` (macOS/Linux), `irm 'https://cursor.com/install?win32=true' | iex` (Windows).
|
|
- OpenCode CLI installed (`opencode` on PATH).
|
|
- Bun for building from source.
|
|
|
|
## Build from source
|
|
|
|
From the repo root:
|
|
|
|
```bash
|
|
bun install
|
|
bun run build:cli
|
|
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/cursor/` - Cursor Agent integration.
|
|
- `src/agent/` - Multi-agent support (Gemini via ACP).
|
|
- `src/opencode/` - OpenCode ACP + hook integration.
|
|
- `src/runner/` - Background service.
|
|
- `src/commands/` - CLI command handlers.
|
|
- `src/ui/` - User interface and diagnostics.
|
|
- `src/modules/` - Tool implementations (ripgrep, difftastic, git).
|
|
|
|
## Related docs
|
|
|
|
- `../hub/README.md`
|
|
- `../web/README.md`
|