Files

nearxos 1d71b3f822 Add v1.1.0 with progress streaming, timeouts, and git validation.

Surface Cursor run progress to stderr and response payloads, enforce
CURSOR_TIMEOUT_SECONDS, validate git repos before delegate, and fix
resume session cwd persistence. Includes docs, tests, and packaging.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-06-19 08:08:14 +03:00

3.2 KiB

Raw Blame History

Configuration

Environment variables use the CURSOR_ prefix (via pydantic-settings).

Variable	Default	Description
`CURSOR_API_KEY`	(empty)	Cursor user API key. Prefer `~/.hermes/.env` when using Hermes launcher.
`CURSOR_DEFAULT_MODEL`	`composer-2.5`	Default Cursor model for delegations.
`CURSOR_DEFAULT_CWD`	`~/Projects`	Default project root when `cwd` is omitted.
`CURSOR_TIMEOUT_SECONDS`	`1800`	Max seconds per delegation/resume run before cancel + error.
`CURSOR_REQUIRE_GIT_REPO`	`true`	When true, `cwd` must be inside a git work tree before delegate.
`CURSOR_SESSIONS_PATH`	`~/.local/share/cursor-mcp/sessions.json`	Persisted session index for resume.
`CURSOR_AUDIT_LOG_PATH`	`~/.local/share/cursor-mcp/audit.jsonl`	JSONL audit trail.

Hermes registration

Recommended launcher (loads CURSOR_* from ~/.hermes/.env):

mcp_servers:
  cursor:
    command: /Users/nearxos/.hermes/mcp_servers/cursor-mcp-env.sh
    enabled: true
    timeout: 1900
    env:
      CURSOR_DEFAULT_CWD: /Users/nearxos/Projects
      CURSOR_DEFAULT_MODEL: composer-2.5
      CURSOR_TIMEOUT_SECONDS: 1800
      CURSOR_REQUIRE_GIT_REPO: true

Set Hermes MCP timeout slightly above CURSOR_TIMEOUT_SECONDS so the server can return a structured timeout error.

Progress streaming

During long runs, cursor-mcp writes human-readable lines to stderr:

[cursor-mcp] status: running
[cursor-mcp] delta: started read_file
[cursor-mcp] step: tool call: edit_file

Hermes captures these in ~/.hermes/logs/mcp-stderr.log.

The tool response JSON also includes:

{
  "status": "finished",
  "progress": [
    {"ts": "...", "kind": "status", "message": "running"},
    {"ts": "...", "kind": "delta", "message": "started read_file", "tool": "read_file"}
  ]
}

Git validation

When CURSOR_REQUIRE_GIT_REPO=true (default), delegate tools fail fast if cwd is not a git repo:

Working directory is not a git repository: /path. Initialize git or set CURSOR_REQUIRE_GIT_REPO=false

Successful validation adds repo metadata to the response git field (root, branch, commit, dirty).

For scratch prototypes:

export CURSOR_REQUIRE_GIT_REPO=false

Timeouts

On timeout the server attempts run.cancel() and returns:

Cursor run timed out after 1800s (run_id=...)

Tune per environment:

Fast patches: CURSOR_TIMEOUT_SECONDS=600
Large refactors: CURSOR_TIMEOUT_SECONDS=3600

Session resume

cursor_delegate_session and cursor_resume store sessions in CURSOR_SESSIONS_PATH.

Each entry includes agent_id, cwd, task_summary, and updated_at.

cursor_resume uses the stored cwd when updating session history (fixed in 1.1.0).

Troubleshooting

Symptom	Fix
`CURSOR_API_KEY is not set`	Add to `~/.hermes/.env`, restart Hermes desktop
`not a git repository`	`git init` in project or disable `CURSOR_REQUIRE_GIT_REPO`
Timeout errors	Increase `CURSOR_TIMEOUT_SECONDS` or narrow task scope
No progress in logs	Ensure stderr is captured; check `mcp-stderr.log`

See also the Hermes skill autonomous-ai-agents/cursor-delegation.

3.2 KiB Raw Blame History