Supervisor

Supervisor is a local, read-only VS Code–family extension that helps you check repo readiness before delegating to an AI agent in Cursor, VS Code, or compatible forks.

It surfaces dirty main, open PRs, stale/cleanup branches, and terminal branches — and copies honest handoff evidence into your agent prompt. Supervisor is read-only — it does not merge PRs, delete branches, publish extensions, run billing, or certify remote CI.

Marketplace Trial / Early Access: MARKETPLACE_LAUNCH.md
Registry follow-up: POST_RELEASE_STORE_BACKLOG.md

Extension id: FreeSpirit.supervisor (Marketplace manifest; editors may normalize to freespirit.supervisor on install).
Publisher: FreeSpirit

Free vs Early Access

Tier	Includes
Free / trial	Basic repo readiness, branch/working-tree facts, dirty-worktree warnings, read-only boundaries, limited GitHub labels
Early Access (€9 one-time)	Full Branch & PR Overview, cleanup review export, advanced handoff/repo-context exports, full GitHub context — updates through v1.0

Unlock: purchase via operator-configured Stripe Payment Link (supervisor.earlyAccess.paymentUrl), then Supervisor: Enter Early Access License. License is stored locally only (v1 — no network validation). See MARKETPLACE_LAUNCH.md.

Who this is for

Developers who use Cursor, VS Code, or compatible forks with AI agents daily.
Anyone who wants a repeatable pre-agent check and a copyable handoff block.
Anyone who has started agent work on the wrong branch or a dirty tree.

Requirements

Editor: VS Code 1.80+ or a compatible fork (for example Cursor).
Git on PATH for local snapshot and readiness features.
Optional: GitHub CLI (gh) for read-only PR/review evidence (no GitHub writes from Supervisor).
Optional: open a workspace whose first folder contains the Supervisor portable proof entrypoint when using Run Local Proof (see PsychoLogicaI/supervisor).

Install (cold user)

From VS Code Marketplace (Trial)

After the operator uploads the VSIX under publisher FreeSpirit with Trial pricing:

In Extensions, search Supervisor: Agent Readiness and install.
Command Palette → Developer: Reload Window.
Open a Git workspace folder and run Supervisor: Open Dashboard.

Extension id: FreeSpirit.supervisor (installed id may appear as freespirit.supervisor).

See MARKETPLACE_LAUNCH.md for Early Access unlock via Stripe Payment Link and local license key.

From a GitHub Release VSIX (alternate)

Open the latest GitHub Release and download supervisor-1.0.0.vsix (optional: verify supervisor-1.0.0.vsix.sha256).
In your editor: Extensions → ⋯ → Install from VSIX… → select the file.
Command Palette → Developer: Reload Window.
Open a Git workspace folder and run Supervisor: Open Dashboard (Ctrl+Shift+P / Cmd+Shift+P).

Or via CLI:

cursor --install-extension supervisor-1.0.0.vsix

Build the VSIX yourself

git clone https://github.com/PsychoLogicaI/supervisor.git
cd supervisor/03_Extension_Prototype
npm run package:vsix

Release-ready output: dist/supervisor-1.0.0.vsix (+ .sha256 checksum beside the VSIX on disk — checksum sidecars are not bundled inside the VSIX). A copy is also written to /tmp/supervisor-1.0.0.vsix for local install scripts.

Rebuild and update in Cursor (local dev)

From 03_Extension_Prototype, one command validates the store manifest, packages the VSIX, removes the legacy extension id if present, and installs into Cursor:

cd supervisor/03_Extension_Prototype
npm run install:cursor

This is local/dev-only — it does not publish to the Marketplace, Open VSX, or any registry. After it finishes, reload open Cursor windows (Command Palette → Developer: Reload Window).

Manual CLI install when you only need the VSIX file:

code --install-extension /tmp/supervisor-1.0.0.vsix
# or
cursor --install-extension /tmp/supervisor-1.0.0.vsix

Marketplace upload status

The extension is packaged for VS Code Marketplace Trial listing under publisher FreeSpirit. Operator upload steps, pricing label, and Stripe Payment Link configuration: MARKETPLACE_LAUNCH.md. Remaining operator decisions: POST_RELEASE_STORE_BACKLOG.md.

Technical preview guide: TECHNICAL_PREVIEW.md
Release notes (v0.1): RELEASE_NOTES_TECHNICAL_PREVIEW_v0.1.md

Status cockpit (Activity Bar)

After install, open the Supervisor icon in the Activity Bar and select Status for a compact view:

Can you delegate work to an agent now? (Ready / Blocked / Needs attention / Limited)
What to do next (plain-language action)
Quick buttons: Open Dashboard, Copy Next Safe Action, Copy Agent Handoff, Refresh

The full Supervisor Dashboard editor tab remains the detail surface for setup checklist, Branch & PR Overview, readiness gates, and evidence.

Cockpit, dashboard, and the status bar share one workspace observation refresh (one Git/gh pass per refresh). Refresh in the cockpit or dashboard updates all surfaces together.

Status meanings (quick reference)

Tier	When
Ready	Local setup looks startable for agent work (advisory)
Needs attention	Review PR state, proof, terminal branch, or ambiguous lifecycle first
Needs setup	Create a feature branch or finish prerequisites
Limited	Partial observation (e.g. no GitHub CLI)
Blocked	Dirty tree, missing Git, or unsupported workspace — do not delegate

PR complete means the prior PR on this branch is merged or closed — switch to default branch and start fresh; do not delegate on the terminal branch.

First-run onboarding

Supervisor: Open Dashboard — review setup state (Git, optional gh, proof availability).
Supervisor: Run Agent Readiness Gate — advisory safe_to_start / needs_attention / blocked from local Git rules.
Supervisor: Generate Agent Handoff Preflight — copy the block into your agent prompt.
Optional: Supervisor: Run Local Proof when the workspace includes the Supervisor proof script.
Supervisor: Clear Local State — removes Supervisor-owned editor storage only (not your Git history).

A one-time dashboard hint may appear after install; dismiss it when you are oriented.

Standard agent workflow is the default public path (everyday language on primary surfaces). Macro / AGENT_RUN workflow is optional and advanced — enable it under Workflow settings only if you use structured operator runs; it is not required for normal agent handoff.

Commands

Command	Purpose
Supervisor: Open Dashboard	Interactive local status and next-action hints
Supervisor: Run Agent Readiness Gate	Read-only local readiness verdict
Supervisor: Generate Agent Handoff Preflight	Copyable handoff evidence for agents
Supervisor: Show Local Git Snapshot	Git snapshot in the output channel
Supervisor: Run Local Proof	Runs portable proof when available in workspace
Supervisor: Clear Local State	Clears Supervisor workspace memento keys only

What Supervisor does not do

Automerge or approve pull requests (claims_ready_to_merge: false by policy).
Write to GitHub (read-only git / gh evidence only).
Delete or clean up branches automatically (cleanup labels are advisory only).
Backend accounts, cloud sync, telemetry, or billing.
Guarantee Open VSX listing, legal compliance, or privacy certification (Marketplace Trial upload is prepared separately).

Privacy

Local-only advisory boundaries; see PRIVACY.md.

Support and changes

SUPPORT.md — how to get help and what to include in reports.
CHANGELOG.md — version history.
LICENSE — usage terms (review before redistribution).

Screenshots

Store listing screenshots are not bundled in the VSIX. Harness evidence and capture guidance: store_assets/screenshots/README.md.

Latest release-readiness evidence: store_assets/screenshots/evidence/agent_run_037/

Repository

Source and issue tracker: https://github.com/PsychoLogicaI/supervisor

Supervisor: Agent Readiness

FreeSpirit