Metadata-Version: 2.5
Name: cursorfleet
Version: 0.1.1
Summary: Unofficial local TUI and workflow harness (observe-only) for Cursor agent teams.
Project-URL: Homepage, https://m9nx.github.io/cursorfleet/
Project-URL: Documentation, https://m9nx.github.io/cursorfleet/
Project-URL: Source, https://github.com/M9nx/cursorfleet
Project-URL: Issues, https://github.com/M9nx/cursorfleet/issues
Project-URL: Changelog, https://github.com/M9nx/cursorfleet/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/M9nx/cursorfleet/blob/main/SECURITY.md
Project-URL: Release notes, https://github.com/M9nx/cursorfleet/releases/tag/v0.1.1
Author: M9nx
License-Expression: MIT
License-File: LICENSE
Keywords: agents,cursor,git-worktree,hooks,observability,tui,workflow
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pydantic>=2
Requires-Dist: textual>=0.80
Requires-Dist: typer>=0.12
Provides-Extra: watch
Requires-Dist: watchfiles>=0.21; extra == 'watch'
Description-Content-Type: text/markdown

<div align="center">

<a href="https://m9nx.github.io/cursorfleet/">
  <img
    src="public-docs/assets/og-card.png"
    alt="CursorFleet — local observe-only harness for Cursor agent teams"
    width="640"
  />
</a>

<p>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
  <img src="https://img.shields.io/badge/status-pre--alpha-orange.svg" alt="Status: pre-alpha" />
  <img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+" />
  <a href="https://pypi.org/project/cursorfleet/"><img src="https://img.shields.io/pypi/v/cursorfleet.svg" alt="PyPI version" /></a>
  <a href="https://m9nx.github.io/cursorfleet/"><img src="https://img.shields.io/badge/docs-m9nx.github.io-222?style=flat-square&logo=readthedocs&logoColor=white" alt="Documentation site" /></a>
</p>

<p>
  <a href="https://m9nx.github.io/cursorfleet/">Documentation</a>
  ·
  <a href="https://pypi.org/project/cursorfleet/">PyPI</a>
  ·
  <a href="https://m9nx.github.io/cursorfleet/getting-started/quickstart/">Quickstart</a>
  ·
  <a href="docs/demo.md">Demo</a>
  ·
  <a href="CONTRIBUTING.md">Contributing</a>
</p>

</div>

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](https://github.com/M9nx/cursorfleet/releases/tag/v0.1.0)** is on
[PyPI](https://pypi.org/project/cursorfleet/) and
[GitHub Releases](https://github.com/M9nx/cursorfleet/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](docs/threat-model.md)).
- **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](docs/evidence/live-validation-index.md). **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](docs/status.md). The M0a capture kit ([spike](spike/README.md)) 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](docs/adr/0005-naming-and-trademark.md)).
- Linux is the tested platform; macOS and Windows are CI-tested only
  ([platform support](docs/platform-support.md)).
- 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](docs/privacy.md)).

## Install

Needs Python 3.11+ and git.

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

From a git checkout (contributors or unreleased `main`):

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

See the [installation guide](https://m9nx.github.io/cursorfleet/getting-started/installation/)
on the docs site and the [release checklist](docs/release-checklist.md).

Optional container (shows under [GitHub Packages](https://github.com/M9nx?tab=packages&repo_name=cursorfleet);
install with pip for normal use):

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

## Quickstart

```bash
# 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](https://m9nx.github.io/cursorfleet/getting-started/quickstart/)
(in-repo: [docs/quickstart.md](docs/quickstart.md)). No Cursor handy? Run the
[synthetic demo](docs/demo.md) (`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](docs/tui.md).

## Documentation

**[Docs site (GitHub Pages)](https://m9nx.github.io/cursorfleet/)** — start with
[Getting started](https://m9nx.github.io/cursorfleet/getting-started/installation/).

In-repo: [Quickstart](docs/quickstart.md) · [governance model](docs/governance.md) ·
[demo](docs/demo.md) · [kit reference](docs/kit.md) · [TUI](docs/tui.md) ·
[`status --json`](docs/status-json.md) · [product contract](docs/product-contract.md) ·
[architecture](docs/architecture.md) · [privacy](docs/privacy.md) ·
[threat model](docs/threat-model.md) · [security review](docs/security-review-v0.1.md) ·
[platform support](docs/platform-support.md) · [hook latency](docs/hook-latency.md) ·
[release checklist](docs/release-checklist.md) · [project status](docs/status.md) ·
[empirical test plan](docs/empirical-test-plan.md) · [follow-ups](docs/follow-ups.md) ·
[docs-site plan](docs/docs-site-plan.md) · [ADRs](docs/adr/README.md) ·
[changelog](CHANGELOG.md)

## Development

```bash
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](CONTRIBUTING.md), [AGENTS.md](AGENTS.md) and [SECURITY.md](SECURITY.md).

## License

MIT, see [LICENSE](LICENSE).
