cursorfleet 0.1.1

Documentation · PyPI · Quickstart · Demo · Contributing

A local TUI and workflow harness for Cursor agent teams: see which local agents and worktrees are doing what, from passive hooks and read-only git, without sending anything anywhere.

Unofficial: CursorFleet is not affiliated with or endorsed by Anysphere or Cursor. "Cursor" is a trademark of its respective owner.

Status

Pre-alpha. v0.1.0 is on PyPI and GitHub Releases. Latest on PyPI: 0.1.1; main may be ahead.

• v0.1 is Observe: no enforcement, no forced approvals, and no cloud-agent visibility (local Cursor sessions only). It is not a security boundary: a malicious or prompt-injected agent can bypass or forge what it shows (threat model).
• Live Cursor (product hooks): maintainer smoke on Linux Cursor IDE 3.22.7 confirmed hook telemetry, subagent lifecycle, and artifact scanning; see live validation index. Q1/Q2 (subagent identity on tool hooks, custom subagent_type naming) remain OPEN; M0a formal matrix is not complete.
• M2.5 active: task-centric observer work (Active Run) is in progress; see status. The M0a capture kit (spike) remains separate.
• Supported surface for claims today: local Cursor IDE (desktop) on Linux for the exercised smoke only; CLI, Agents Window, worktrees, and parallel subagents are not claimed until matrix PASS. The Cursor CLI, the Agents Window, Cursor-managed and manual worktrees, parallel subagents and cloud agents are not claimed.
• The name "CursorFleet" is a working name; the final name is a release gate (ADR 0005).
• Linux is the tested platform; macOS and Windows are CI-tested only (platform support).
• Cursor is the only officially supported IDE; internals are adapter-ready but no other adapter is planned for v0.1.
• Local only: no network calls, no telemetry, no accounts (checked by a test). It never stores prompts, model thinking, responses, file contents, command output, environment variables, emails or transcript paths (privacy).

Install

Needs Python 3.11+ and git.

uv tool install cursorfleet    # or: pipx install cursorfleet
cursorfleet --version

From a git checkout (contributors or unreleased main):

git clone https://github.com/M9nx/cursorfleet && cd cursorfleet
uv tool install .

See the installation guide on the docs site and the release checklist.

Optional container (shows under GitHub Packages; install with pip for normal use):

docker run --rm ghcr.io/m9nx/cursorfleet:0.1.0 --help

Quickstart

# from the repository root (Git is required; no --allow-non-git)
cursorfleet init --cursor --dry-run   # review the exact diff first
cursorfleet init --cursor             # install the observe-only hooks and kit (once per repo)
# ...work with Cursor agents as usual...
cursorfleet doctor                    # check hooks, runtime dir and spool
cursorfleet tui                       # open the dashboard (needs an interactive terminal)
cursorfleet status --json             # stable machine-readable snapshot for scripts
cursorfleet uninstall                 # remove exactly what init added

Full walkthrough: Quickstart on the docs site (in-repo: docs/quickstart.md). No Cursor handy? Run the synthetic demo (scripts/demo.sh).

Dashboard keys: o overview, l timeline, w worktrees, g gates, e evidence, v violations (v0.2 placeholder), / filter, p pin, t tiles (160+ columns), r re-read, ? help, q quit. The TUI only observes: silence shows as STALE / OFFLINE, never idle, and gate tiles are heuristic and non-authoritative, not proof that anything passed. Details: docs/tui.md.

Documentation

Docs site (GitHub Pages) — start with Getting started.

In-repo: Quickstart · governance model · demo · kit reference · TUI · status --json · product contract · architecture · privacy · threat model · security review · platform support · hook latency · release checklist · project status · empirical test plan · follow-ups · docs-site plan · ADRs · changelog

Development

uv sync --all-extras
uv run cursorfleet --version
uv run ruff check . && uv run ruff format --check . && uv run mypy src && uv run pytest

Regenerate schemas with uv run python scripts/gen_schemas.py. See CONTRIBUTING.md, AGENTS.md and SECURITY.md.

License

MIT, see LICENSE.