Skip to main content

​
Overview

HAPI supports Cursor Agent CLI for running Cursor’s AI coding agent with remote control via web and phone.

​
Requirements

​
Install Cursor Agent CLI

curl https://cursor.com/install -fsS | bash

​
Verify Installation

agent --version
Make sure the agent command is available on your PATH.

​
Starting a Session

​
Basic Usage

hapi cursor                    # Start new Cursor Agent session
hapi cursor resume <chatId>    # Resume specific chat
hapi cursor --continue         # Resume most recent chat

​
With Options

hapi cursor --mode plan        # Start in Plan mode
hapi cursor --mode ask         # Start in Ask mode
hapi cursor --yolo             # Bypass approval prompts
hapi cursor --model <model>    # Specify model
hapi cursor --resume <chatId>  # Resume specific chat

​
Available Flags

FlagDescription
resume <chatId>Resume a specific chat by ID
--continueResume the most recent chat
--resume <chatId>Alternative resume syntax
--mode <mode>Set permission mode: plan or ask
--planStart in Plan mode (shortcut)
--yoloBypass approval prompts (uses --force)
--forceExplicit force flag
--model <model>Specify which model to use
--hapi-starting-modeSet initial mode: local or remote
Additional Cursor Agent flags are passed through. See Cursor CLI docs for all options.

​
Permission Modes

Cursor Agent supports these permission modes:

Default

Standard agent behavior with approval prompts

Plan Mode

Design approach before implementing changes

Ask Mode

Explore code without making edits

Yolo

Bypass all approval prompts (use with caution)
Set mode via --mode flag or change from the web UI during a session. See shared/src/modes.ts:13-14 for mode definitions.

​
Session Modes

​
Local Mode

Full interactive experience from terminal: 
hapi cursor
In local mode:
  • Direct terminal interaction with Cursor Agent
  • Real-time responses
  • Full feature set available
  • Messages from web/phone are queued

​
Remote Mode

Control entirely from web/phone: 
hapi cursor --hapi-starting-mode remote
In remote mode:
  • Uses agent -p with --output-format stream-json
  • Includes --trust flag for tool execution
  • Each message spawns one agent process
  • Session continues via --resume
  • No terminal interaction required
In remote mode, --trust is used for tool execution. Tools run without per-request approval. Use --yolo for full bypass.

​
Resume Functionality

Cursor Agent has robust session resume capabilities: 
# Resume by chat ID
hapi cursor resume chat_abc123

# Resume using flag syntax
hapi cursor --resume chat_abc123

# Resume most recent
hapi cursor --continue

​
Finding Chat IDs

To list previous chats and get chat IDs: 
agent ls
You can also view chat history in the HAPI web UI.

​
Examples

​
Start New Session

hapi cursor

​
Start in Plan Mode

hapi cursor --mode plan
Plan mode designs the approach before coding.

​
Start in Ask Mode

hapi cursor --mode ask
Ask mode explores code without making edits.

​
Resume Specific Chat

hapi cursor resume chat_abc123

​
Resume Most Recent

hapi cursor --continue

​
Start with Yolo Mode

hapi cursor --yolo
Yolo mode bypasses all approval prompts. Use only in trusted environments.

​
Specify Model

hapi cursor --model claude-4.5-sonnet

​
Integration

Once running, your Cursor Agent session appears in:
  • HAPI web app
  • Telegram Mini App
You can:
  • Monitor session activity in real-time
  • Approve permissions from your phone
  • Send messages to the agent
  • Switch between local and remote modes
  • Change permission modes on the fly
  • View file changes and diffs

​
Limitations

​
Tool Approval in Remote Mode

In remote mode, the --trust flag is used, which means tools run without per-request approval. This is required for remote operation but reduces granular control. Workaround: Use permission modes to control overall behavior:
  • default - Standard behavior
  • plan - Plan first, then implement
  • ask - Read-only exploration
  • yolo - Full bypass (use carefully)

​
Session Resume

Cursor Agent sessions are chat-based. To resume:
  1. Get the chat ID from agent ls or the web UI
  2. Pass it to --resume <chatId> or --continue
Each resumed session continues the same conversation context. 
hapi auth status        # Check authentication
hapi runner status      # View background service status
hapi runner list        # List active HAPI sessions
agent ls                # List Cursor chats
hapi doctor             # Run diagnostics

​
External Resources

​
Source Reference

  • Command implementation: cli/src/commands/cursor.ts
  • Session runner: cli/src/cursor/runCursor.ts
  • Permission modes: shared/src/modes.ts:13-14
  • User guide: docs/guide/cursor.md

Build docs developers (and LLMs) love

Get started for freeTalk to us