wushenghua/hapi

Fork 0

mirror of https://github.com/wu736139669/hapi.git synced 2026-08-05 06:24:37 +00:00

Files

T

History

Mao MrandGitHub c9be2894ac feat(cursor): add support for Cursor Agent CLI integration (#236 )

* 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

2026-03-03 10:02:47 +08:00

.github/workflows

refactor: rename daemon to runner throughout codebase

2026-01-19 11:12:48 +08:00

bin

refactor(cli): extract platform validation and error reporting from binary launcher

2026-03-02 11:58:08 +08:00

npm

feat: add npx/bunx binary distribution support

2025-12-24 14:39:05 +08:00

scripts

build baseline variant for linux x64.

2026-03-02 13:11:06 +08:00

src

feat(cursor): add support for Cursor Agent CLI integration (#236 )

2026-03-03 10:02:47 +08:00

tools

init

2025-12-16 15:03:50 +08:00

.cursorrules

init

2025-12-16 15:03:50 +08:00

.gitattributes

init

2025-12-16 15:03:50 +08:00

.gitignore

Fix npm release wrapper package

2026-01-03 22:22:45 +08:00

.npmignore

feat: add npx/bunx binary distribution support

2025-12-24 14:39:05 +08:00

.npmrc

init

2025-12-16 15:03:50 +08:00

bunfig.toml

fix(cli): resolve path alias with bun link using bunfig.toml configuration

2025-12-22 16:44:27 +08:00

LICENSE

chore: migrate to AGPL-3.0-only

2026-01-04 20:45:15 +08:00

NOTICE

refactor: rename daemon to runner throughout codebase

2026-01-19 11:12:48 +08:00

package.json

Release version 0.15.4

2026-03-01 11:05:36 +08:00

README.md

feat(cursor): add support for Cursor Agent CLI integration (#236 )

2026-03-03 10:02:47 +08:00

tsconfig.json

feat: rename server package to hub

2026-01-27 19:51:21 +08:00

vitest.config.ts

init

2025-12-16 15:03:50 +08:00

README.md

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

Start the hub and set env vars (see ../hub/README.md).
Set the same CLI_API_TOKEN on this machine or run hapi auth login.
Run hapi to start a session.
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:

bun install
bun run build:cli
bun run build:cli:exe

For an all-in-one binary that also embeds the web app:

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).

../hub/README.md
../web/README.md

README.md

hapi CLI

What it does

Typical flow

Commands

Session commands

Authentication

Runner management

Diagnostics

Other

Configuration

Required

Optional

Runner

Worktree (set by runner)

Storage

Requirements

Build from source

Source structure

Related docs