901f17d0ca
* feat(pi): support Pi slash commands from HAPI web (compact/session/model/help)
Pi runs as 'pi --mode rpc' over piped stdio, so TUI slash commands typed in
web chat previously fell through to the LLM as plain text and silently did
nothing (notably /compact).
- shared: add Pi builtin slash command list (help/compact/session/model) so
the web / menu exposes them; web test updated to match
- cli: intercept Pi builtin commands in runPi's user-message path
* /compact [instructions] -> Pi compact RPC (120s timeout, works while
streaming; summary + token delta reported back as chat messages)
* /session -> get_session_stats formatted stats
* /model [modelId] -> list/switch via set_model
* /help -> supported-commands list
* other Pi TUI builtins (/tree, /export, /reload, ...) -> explicit
terminal-only notice instead of silent LLM pass-through
* unknown slash text still passes through (extension commands, skills,
templates keep working)
- gate the prompt pump with piCompactInFlight so queued prompts are not
rejected by Pi mid-compaction; buffer commands until ready like prompts
- ListSlashCommands RPC merges HAPI builtins with Pi extension commands
- tests: parser unit tests + runPi integration tests (compact execution,
streaming steer interception, failure reporting, FIFO blocking, model
switch, unsupported commands, slash list merge)
- docs: document Pi slash command support in docs/guide/agents.md
* fix(pi): address review findings on slash command lifecycle
- compact timeout: fail the session (indeterminate outcome, runtime lease
poisoned) instead of reopening the prompt FIFO into a possibly-compacting
Pi; pump only when cleanup has not been initiated
- special commands: release the cancellation reservation before executing so
a cancel landing mid-command is not acknowledged (hub would delete the
queued row while the command still runs)
- tests: drop the duplicated slash-command describe block; add focused tests
for compaction timeout with a queued prompt and cancellation during an
in-flight special command
* fix(pi): route slash commands through the prompt FIFO and reject ambiguous models
- slash commands now share the prompt FIFO with ordinary messages: a
/compact or /model typed after a queued prompt dispatches only after it
(and after the active turn settles), instead of jumping the queue from
the preparation chain
- the pump dispatches special entries out-of-band while piSpecialCommandInFlight
keeps the FIFO blocked; steer promotion refuses slash commands
- /model <id> prefers an exact provider/modelId match and reports bare IDs
shared by multiple providers as ambiguous instead of picking the first
- tests: FIFO ordering (queued prompt before /compact), steer-delivered
/compact queued until settle, ambiguous/qualified model selection
* fix(pi): keep /compact interruptible, honor extension precedence, require token boundary
- head-of-line /compact dispatches even while Pi is streaming (Pi's
compact() aborts the active generation itself); every other queued item
still waits for the stream to settle, preserving FIFO order
- discovered extension commands / prompt templates override same-name
builtins at message time, matching the slash-list merge precedence
- parsePiSpecialCommand requires a command-token boundary, so path-like
text such as /compact.md or /model/config stays an ordinary prompt
- tests: interrupt rule, extension collision, reserved-name path prefixes,
non-compact commands waiting for stream settle
* fix(pi): honor cancellation acknowledged during slash-command discovery
A cancel arriving while the chain awaits get_commands (cold cache) was
acknowledged via the preparing reservation but never re-checked, so a
canceled /compact could still execute. Re-check the cancellation marker
after discovery and drop the message before dispatch.
* fix(pi): qualify /model selectors and report failed slash RPCs once
- /model lists provider-qualified selectors (openai/gpt-5.2) so duplicate
bare IDs remain usable and copy-pasteable; current model is qualified too
- compact/set_model failures are owned by the awaited slash/config handlers:
the common response handler no longer emits the raw Pi error a second time
- tests: qualified listing with duplicate providers, single-message failure
reporting for rejected /compact and /model
* fix(pi): consume slash-command queue row at dispatch
Special commands (/compact, /session, /model, /help) are executed by HAPI
itself and never delivered to Pi as prompts. Consumption was deferred until
the command finished, so a /compact run — an LLM summarization pass that can
take minutes — left the row stuck in the web queued bar for its whole
duration, then surfaced as a sent message. Consume the row the moment
dispatch starts; failures still surface via the explicit event message.
* fix(pi): guard special-command dispatch against unexpected rejections
* ci: retry Codex PR Review after infra failure (proxy 503)
* fix(pi): keep session queued-thinking grace during /compact dispatch
The queued-thinking grace is session-scoped, so clearing it while
acknowledging a dispatch-time /compact row also drops the grace for any
prompt queued behind it. /compact keeps running for minutes without
toggling Pi thinking state, which would leave the web session looking idle
while compaction and the following prompt are still pending. Only the
fast, synchronous commands (/session, /model, /help) clear the grace.
* fix(pi): render compaction summary as a dedicated chat block
The manual /compact RPC result was reported as two plain message
events ("📦 Compaction completed (tokens: …)" + "📦 Compaction
summary: …"), which the web chat renders as tiny centered status
lines — unusable for a real summary payload. Emit a structured
compact-summary event instead (summary + token delta) and render
it as an independent block: header with the delta and the summary
markdown in a scrollable panel.
Also emit the same structured event when importing Pi session
files (compaction entries), and queue the event lossless like
other user-visible messages so a disconnect cannot drop it.
Verified: bun typecheck clean; bun run test exit 0 (cli 2481
passed, web 2451 passed, hub/shared clean); runPi/loop/apiSession/
piSessions/presentation suites green.
* fix(pi): address HAPI Bot findings on compact dispatch and import
- Track compaction as thinking for its whole duration: /compact runs for
minutes without a Pi streaming event, so the 15s queued-thinking grace
alone left the web session looking idle while compaction and any queued
prompts were still pending (updateThinkingState around the compact RPC).
- Imported Pi compaction summaries must use the event envelope
(content.type: 'event') like the live wrapper's compact RPC result; the
codex payload envelope is dropped by the web normalizer. Extend
CodexImportedMessageSchema with the event variant.
* fix(pi): /model retries discovery when the model cache is empty
Startup model discovery can be late or fail once; using only the cached
catalog made /model report valid models as unknown. getPiModels() falls
back to the get_available_models RPC on an empty cache, used for both
listing and switching.
* fix(pi): interrupt in-flight /compact on Abort; surface startup model rejection
- The Abort action no longer waits on the runtime-mutation lease when a
manual /compact is in flight (compaction can hold it for up to 120s,
blowing the 25s abort deadline and failing closed). It sends the abort
RPC directly so Pi cancels its compaction AbortController; the compact
RPC's 'Compaction cancelled' error is not double-reported as a failure
since Pi already emits the compaction_end(aborted) lifecycle event.
- A rejected detached startup set_model now emits a visible ⚠️ event into
chat instead of only a debug log, restoring the pre-existing behavior.
* fix(pi): close the Abort race when /compact is queued on the mutation lock
Abort previously assumed an in-flight /compact always had its RPC issued;
the command is marked active at queue dispatch, but the compact RPC is sent
only after the runtime-mutation lock is acquired. An Abort landing in that
gap acknowledged success while the compact RPC still ran afterwards.
Track the compact's rpcStarted/cancelled state: Abort cancels a not-yet-
started compact in place (the queued callback skips it), and interrupts a
started one via the abort RPC as before.
* fix(pi): persist provider-qualified selection after /model switch
The success path updated currentModel/currentProvider and keepalive with a
bare model ID, leaving metadata.piSelectedModel on the previous provider.
The web picker prefers that metadata for selection, context-window
resolution, and effort options, so a switch like openai/gpt-5.2 ->
azure/gpt-5.2 was invisible. Persist piSelectedModel with the full
provider/modelId pair on every confirmed switch.
* fix(pi): retire pending extension UI requests when /compact interrupts a turn
The streaming-interrupt path sent the compact RPC without cancelling
pending extension UI requests first, unlike the Abort path. Editor
requests have no timeout, so the web could stay stuck on a stale
input/permission card and a later answer could be routed to the aborted
turn. Cancel all pending requests (with a response) before compacting.
* fix(pi): fail closed when the direct compact-abort RPC times out
The in-flight /compact abort branch awaited the abort RPC without the
ordinary Abort path's timeout handling: an unanswered abort left the
compaction outcome indeterminate (the compact RPC keeps the mutation
lease for up to 120s) while the wrapper still looked live. Fail the
session on PiRpcTimeoutError, mirroring the standard abort fail-closed
path.
---------
Co-authored-by: swear01 <swear01@users.noreply.github.com>
15 KiB
Supported Agents
HAPI is a wrapper around AI coding agents. One CLI (hapi <agent>) starts any supported agent locally and exposes the same session for remote control from the web app, PWA, and Telegram — with permission prompts, message queueing, and seamless handoff between terminal and phone.
Support matrix
| Agent | Command | Integration | Local | Remote | Permission modes | Resume |
|---|---|---|---|---|---|---|
| Claude Code | hapi / hapi claude |
Terminal wrapper (local) + Claude Agent SDK (remote) | ✓ | ✓ | default acceptEdits auto bypassPermissions plan |
✓ |
| Codex | hapi codex |
TUI wrapper (local) + codex app-server JSON-RPC (remote) |
✓ | ✓ | default read-only safe-yolo yolo (+ plan collaboration mode) |
✓ |
| Cursor Agent | hapi cursor |
ACP (agent acp); legacy stream-json resume |
✓ | ✓ | default plan ask debug autoReview yolo |
✓ |
| Grok Build | hapi grok |
ACP (grok agent stdio) |
✓ | ✓ | default auto plan bypassPermissions |
✓ |
| GitHub Copilot | hapi copilot |
ACP (copilot --acp --stdio) |
✓ | ✓ | default read-only safe-yolo yolo |
✓ |
| Kimi | hapi kimi |
ACP (kimi acp) |
✓ | ✓ | default read-only safe-yolo yolo |
✓ |
| OpenCode | hapi opencode |
ACP (opencode acp) |
✓ | ✓ | default plan yolo |
✓ |
| Antigravity (agy) | hapi agy |
Interactive PTY + hooks | ✓ | ✓ | request-review always-proceed |
✓ |
| Pi | hapi pi |
pi --mode rpc (JSON-line RPC over stdio) |
— | ✓ | none (always auto-approve) | ✓ |
| Gemini CLI | — | Removed — Google sunset the consumer Gemini CLI (2026-06-18) | — | — | — | — |
Gemini is no longer launchable: hapi gemini is kept as a tombstone command that prints a clear error, and existing Gemini sessions remain viewable in the web UI but cannot be resumed.
Common concepts
ACP
Most remote integrations speak the Agent Client Protocol (ACP) over stdio through a shared HAPI backend. ACP gives remote sessions bidirectional permission approval, plan/todo updates, question UI, model catalogs, and session resume via session/load. Cursor, Grok, Copilot, Kimi, and OpenCode remote sessions all run over ACP.
Permission modes
Permission modes are per-agent — each flavor exposes its own set (see the matrix above). Set the mode at launch with --permission-mode <mode> or a shortcut flag (--yolo, --plan, --auto-review, depending on the agent), and switch it mid-session from the web UI. Semantics vary per agent; see the per-agent sections below.
Local and remote mode
Every session is either local (driven from the terminal) or remote (driven from web/phone). Switching is seamless and keeps the same session state:
- Remote → local: press double-space in the terminal.
- Local → remote: send a message from the web UI or phone; the session switches automatically.
See Seamless Handoff for details.
Resuming sessions
hapi resume # Interactive picker of resumable sessions on this machine
hapi resume <session-id> # Resume a specific HAPI session
hapi resume works for every flavor except Gemini. An active remote session is handed off to the local terminal first. Pi is the exception in the other direction: it has no local input path, so Pi sessions always resume in remote mode.
Cursor Agent
HAPI supports Cursor Agent CLI for running Cursor's AI coding agent with remote control via web and phone.
When Cursor resumes mid-idle (for example after a Shell notify_on_output wake) and emits ACP activity, HAPI bumps session thinking over the normal session-alive keepalive so the list does not stay stuck idle. See FAQ.
Prerequisites
Install Cursor Agent CLI:
- macOS/Linux:
curl https://cursor.com/install -fsS | bash - Windows:
irm 'https://cursor.com/install?win32=true' | iex
Verify installation:
agent --version
Usage
hapi cursor # Start Cursor Agent session
hapi cursor resume <chatId> # Resume a specific chat
hapi cursor --continue # Resume the most recent chat
hapi cursor --plan # Start in Plan mode (shortcut)
hapi cursor --mode plan # Start in Plan mode
hapi cursor --mode ask # Start in Ask mode
hapi cursor --auto-review # Start with Auto-review (Smart Auto)
hapi cursor --yolo # Bypass approval prompts (--force)
hapi cursor --model <model> # Specify model
hapi cursor --cursor-worktree # Cursor-native worktree (auto-named)
hapi cursor --cursor-worktree feature-x # Cursor-native worktree (named)
hapi cursor --cursor-add-dir ../shared # Extra workspace root (repeatable)
Permission modes
| Mode | Description |
|---|---|
default |
Standard agent behavior |
plan |
Plan mode - design approach before coding |
ask |
Ask mode - explore code without edits |
debug |
Debug mode - hypotheses + instrumentation |
autoReview |
Auto-review (Smart Auto) - allowlist/sandbox/classifier instead of full YOLO |
yolo |
Bypass approval prompts |
Set mode via --plan / --mode / --permission-mode / --auto-review, or change from the web UI during a session.
Cursor-native worktree & multi-root
- New Session Worktree for Cursor uses Cursor's
--worktree(~/.cursor/worktrees/<repo>/<name>), not HAPI's sibling-directory worktree. - Exception: if the spawn
directoryis already a linked git worktree (HAPI feature worktree,driver/, etc.), the runner does not pass--cursor-worktree— nesting hangs ACP initialize (#1085). Use the directory as cwd instead. - Mid-session: send
/worktree,/apply-worktree,/delete-worktree, or/add-dir <path>(isolated pass-through). - CLI:
hapi cursor --cursor-worktree feature-x --cursor-add-dir ../shared - ACP ignores Cursor's plain-text
Using worktree: …stdout banner so remotesessionType: worktreecan initialize (fixed in #1085). Other non-JSON ACP stdout remains a fatal protocol error.
Slash pass-through (remote)
These commands are isolated in the queue and forwarded to the agent (ACP prompt or legacy -p):
/compress /summarize /compact /model /multitask /best-of-n /worktree /apply-worktree /delete-worktree /add-dir /context /fork /auto-review
Interactive TUI-only commands (/config, /mcp, /sandbox, /btw, /rewind, …) are not supported remotely.
Modes
- Local mode - Run
hapi cursorfrom terminal. Full interactive experience. - Remote mode - Spawn from web/phone when no terminal. New Cursor sessions use
agent acpwith HAPI permission approval, plan/question UI, and richer tool updates. Legacy sessions created before the ACP migration may still resume via the oldagent -pstream-json path temporarily.
Limitations
- Multitask UI -
/multitaskis slash-driven; HAPI does not yet provide an Agents Window-style fleet pane. Subagentcursor/tasknotifications show as CursorTask cards when the agent emits them. - Legacy sessions - Cursor sessions created before the ACP migration can still resume temporarily via stream-json. Start a new Cursor session to get ACP permissions, plans, todos, and question support.
- Session resume - ACP sessions resume through
session/load. Old stream-jsonsession_idvalues are not loadable via ACP; those sessions keep using the legacy path until you start fresh.
Legacy stream-json safety: AskQuestion behavior
New cursor remote sessions go through ACP, which handles AskQuestion via the bidirectional cursor/ask_question extension method and is immune to the issue below. The intercept described here exists only for legacy sessions that resume via the older agent -p stream-json launcher.
When running cursor-agent under --print --output-format stream-json, the cursor-agent CLI returns a synthetic Questions skipped by the user, continue with the information you already have response for the AskQuestion tool because there is no IDE surface to render the question. The agent's underlying model can interpret this as legitimate user consent and act on it.
HAPI's legacy event converter intercepts this synthetic response and rewrites it to an explicit no_input_surface error (status: failed), so downstream consumers (web UI, Telegram, log readers) surface the fabrication as an error instead of silently passing through fabricated consent. The intercept scans the raw tool_call payload for the literal marker text and is scoped to AskQuestion-shaped (and converter-fallback name=unknown) calls; legitimate read/write/function tools are not affected.
The intercept drains naturally with the legacy session population - resumed pre-ACP sessions are the only path that still hits this code.
Tracking issue: tiann/hapi#784.
Grok Build
HAPI can run the official Grok Build CLI locally and control the same coding session remotely from the Web/PWA.
Install
Install Grok Build using the official installer:
::: code-group
curl -fsSL https://x.ai/cli/install.sh | bash
irm https://x.ai/cli/install.ps1 | iex
:::
Verify the installation:
grok version
Authenticate
HAPI reuses the Grok CLI's local authentication. On a headless runner machine, authenticate once with device-code login:
grok login --device-auth
Alternatively, configure an xAI API key in the runner environment:
export XAI_API_KEY="xai-..."
Do not place API keys in HAPI configuration files, logs, or a repository.
Start a session
Start the native Grok Build TUI:
hapi grok
Start with explicit launch settings:
hapi grok --model grok-4.5 --effort low --permission-mode default
hapi grok --yolo # Shortcut for --permission-mode bypassPermissions
Sessions created from a HAPI runner start in remote mode automatically. Terminal-created sessions start in the native Grok TUI and can switch to remote control without parsing terminal output.
Permission modes
Grok exposes four permission modes:
default— tool requests are shown in HAPI for approval or denial.auto— Grok's own Auto mode: HAPI forwards Grok's/autocommand to the session. Auto depends on account and CLI-build availability — if Grok does not advertise the/autocommand, HAPI falls back todefaultand posts a notice in the session.plan— HAPI asks Grok to plan only and rejects tool execution requests.bypassPermissions— tool requests are automatically approved for the session (--yoloshortcut).
Use bypassPermissions only in a trusted workspace.
Resume and handoff
Remote mode uses Grok's ACP stdio agent (grok agent stdio). HAPI stores the native Grok session ID and uses it for:
- ACP
session/loadafter a restart. grok --resume <session-id>when switching back to the native TUI.hapi resume <hapi-session-id>from a terminal.
For a new local session, HAPI supplies a UUID with grok --session-id, so the session can be resumed without scraping the fullscreen TUI.
Fork and rewind
When the Grok CLI build advertises them, HAPI uses Grok's ACP extension methods to fork the conversation (current point or from an earlier message, via _x.ai/session/fork) and to rewind the conversation to an earlier prompt (via _x.ai/rewind/*). Capabilities are probed per session, so older builds simply hide these controls.
Model and effort controls
The Create page discovers Grok's ACP model catalog and the reasoning-effort choices advertised for each model. Remote sessions can switch both model and effort between turns; HAPI applies them through ACP session/set_model and session/set_mode. From the terminal, pick them at launch with --model <model> and --effort <level>.
HAPI also exposes Grok's common slash commands, discovers skills from .grok/skills, ~/.grok/skills, and shared .agents/skills, and asks Grok to set a concise HAPI session title after the first normal prompt.
Current limitations
- OAuth/device-code login must be completed outside the HAPI Web UI.
- Grok subscription, credit, and model availability are controlled by xAI.
If a remote session reports authentication failure, run grok login --device-auth on the runner machine and retry.
Other agents
-
Claude Code (
hapi/hapi claude) — the default and recommended flavor; local sessions wrap the native TUI, remote sessions drive the Claude Agent SDK. Claude Code docs -
Codex (
hapi codex) — OpenAI's Codex CLI; remote sessions talk tocodex app-serverover JSON-RPC, with a dedicatedplancollaboration mode. openai/codex -
GitHub Copilot (
hapi copilot) — Copilot CLI over ACP (copilot --acp --stdio). GitHub Copilot -
Kimi (
hapi kimi) — Moonshot AI's Kimi CLI over ACP (kimi acp). MoonshotAI/kimi-cli -
OpenCode (
hapi opencode) — the open-source OpenCode agent over ACP (opencode acp). opencode.ai -
Antigravity (
hapi agy) — Google's Antigravity CLI (agy), driven as an interactive PTY with hook-based permission bridging. Google Antigravity -
Pi (
hapi pi) — the Pi coding agent running aspi --mode rpc(JSON-line RPC over piped stdio); remote-control only, no local TUI input path. badlogic/pi-monoHAPI translates a subset of Pi's TUI slash commands to native Pi RPC calls, so they work from the web chat as well:
/compact [instructions]— manually compact context with optional custom summary instructions (runs Pi'scompactRPC; the summary is rendered as a dedicated block in the chat with the token delta in its header)./session— show session stats (messages, tokens, cost, context usage)./model [modelId]— show the current model and available models, or switch with/model <modelId>./help— list the commands supported from HAPI.
Pi's extension commands and prompt templates (discovered via
get_commands) keep working from the/menu, and skills are available through$skill-namelike other ACP flavors. Other Pi TUI builtins (e.g./tree,/export,/reload) cannot run over RPC; typing them in web shows an explicit "terminal-only" notice instead of silently forwarding the text to the model.
Related
- How it Works - Architecture and data flow
- Quick Start - Install HAPI and start your first session