# 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`):

```yaml
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.

**Hermes YAML note:** values under `mcp_servers.*.env` must be **strings** (quote numbers/booleans), e.g. `CURSOR_TIMEOUT_SECONDS: '1800'`.

## Progress streaming

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

```text
[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:

```json
{
  "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:

```text
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:

```bash
export CURSOR_REQUIRE_GIT_REPO=false
```

## Timeouts

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

```text
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`.