Skip to content
BranchesTags

Repository files navigation

oh-my-cursor

Independent, versioned MAP (Multi-Agent Protocol) engine for Cursor — hooks, skills, install tooling, and a fail-closed merge gate for multi-agent PR workflows.

CI

Status

What is MAP?

oh-my-cursor is the engine package. After install, it runs inside consumer git repos (your projects) via Cursor hooks:

oh-my-cursor (this repo)              Consumer repo (your project)
├── hooks/review_gate.py   ─install─►  ~/.cursor/hooks/  or  repo/.cursor/hooks/
├── skills/*               ─copy────►  ~/.cursor/skills/
├── scripts/install.py
└── tests/

                                      .review/          ← ephemeral session state (not committed)
                                      .specs/           ← specs (optional, may be committed)

Commander (parent agent) orchestrates subagents; hooks record evidence, enforce role permissions, and block merge until review requirements are met.

Quick start

If you cloned before 2026-06-09 (pre-public history rewrite), reset or re-clone — see Contributing — Existing clones.

chmod +x hooks/run_tests.sh
./hooks/run_tests.sh

Install

Pin a release tag for production. Prefer --copy (copies review_gate.py into ~/.cursor/hooks/). --link symlinks to your clone — if the clone path changes or is untrusted, hooks may break or execute unexpected code; use only for active engine development with --i-know-symlink-risk.

chmod +x install.sh
./install.sh --copy              # production default → ~/.cursor
./install.sh --link --i-know-symlink-risk
./install.sh --project /path/to/repo
python3 scripts/install.py --doctor --security

Hook runtime needs Python 3 stdlib only (no pip). Lint/typecheck/coverage for contributors use requirements-dev.txt — see Development.

Cloud agents: Cursor cloud VMs do not load user-level ~/.cursor/hooks.json. Project, team, or enterprise hooks require their hook files to be present in the cloud workspace—typically commit .cursor/, or install MAP with ./install.sh --project /path/to/repo into the repository that the cloud agent clones. Some lifecycle hooks (including sessionStart, stop, and subagentStop) may not fire in cloud exactly as they do in Desktop, so MAP markers and merge-gate evidence may remain incomplete even with --project. Use Desktop for full MAP enforcement; --project remains the correct packaging for hooks that are available in cloud. Details: docs/install.md.

Details: docs/install.md · docs/security.md · docs/state-migration.md · docs/integrations/issue-to-pr.md

Set OMC_ROOT to this clone for CLI examples in skills:

export OMC_ROOT="$(pwd)"

1. Feature modules

Module Location Purpose
Install / doctor scripts/install.py, install.sh Copy or link hooks, skills, agents into ~/.cursor or a project .cursor/; omc doctor validates hook count, secret, paths
State migration scripts/migrate_map_state.py Move legacy .review-session/ paths to canonical .review/session/
Merge gate core hooks/review_gate.py Phase machine, queues, role matrix, HMAC markers, merge validation
Cursor hooks hooks/hooks.json.template Merge gate, tool permissions, Task alignment, role assignment, marker recording, stop driver, session resume
Four workflows skills/ multi-agent-pr, map-hyperplan, map-security, map-refactor
Plan → hyperplan bridge docs/workflows/plan-then-hyperplan.md Plan mode → adversarial review → merge-back into plan → implement
Schemas hooks/schemas/ debate-round, spec-frontmatter, security-queue, quarantine-tests, etc.

2. Review state (.review/ in consumer repos)

All workflow progress is stored under .review/ in the target git repo. These files are ephemeral — do not commit them. A new commit changes HEAD and invalidates prior markers and verdicts until reviewers re-run.

This engine repo does not commit .review/ — session artifacts belong in consumer project repos only. .review/ is listed in .gitignore here.

flowchart TB
    subgraph session["Session contract"]
        config["config.json — active, workflow, tier, models, session_id"]
        progress["progress.json — phase, completed, last_spawn"]
    end

    subgraph runtime["Runtime roles"]
        roles["roles/{subagent_id}.json — logical_role, model"]
    end

    subgraph evidence["Merge evidence"]
        markers["session/{branch}/{sha}/*.json — HMAC-sealed markers"]
        summary["session-summary.json — human-readable summary"]
        verdict["verdict.json — Commander synthesis"]
    end

    subgraph queues["Loop queues"]
        fixq["fix-queue.json — multi-agent-pr P0/P1 fixes"]
        criticq["critic-queue.json — hyperplan pending critics"]
        secq["security-queue.json — unverified High+ findings"]
    end

    subgraph reports["Reports"]
        debate["reports/debate-round-N.json"]
        baseline["reports/baseline-{sha}.json"]
        regression["reports/regression-{sha}.json"]
        security["reports/security-{date}.md"]
    end

    config --> progress
    roles --> markers
    markers --> verdict
    fixq --> progress
    criticq --> progress
Loading

Canonical paths

Artifact Canonical (write) Legacy (read until v2.0.0)
Markers .review/session/<branch>/<sha>/ .review-session/...
Summary .review/session-summary.json .review-session.json
Verdict .review/verdict.json .review-verdict.json
MAP config .review/config.json —

Migrate: docs/state-migration.md

Core files — who writes, who reads

File Written by Read by Meaning
config.json Commander (after AskQuestion) All hooks Session switch: active, workflow, tier, models, session_id
progress.json Commander + advance-* CLI sessionStart, stop, permission gates Current phase, completed subagents, last spawn
roles/{id}.json subagentStart hook Write/Delete/Shell gates logical_role for this subagent (e.g. reviewer-grok)
session/.../reviewer-*.json subagentStop hook (HMAC seal) validate_review_state Non-forgeable subagent completion evidence
verdict.json Commander (after synthesis) Merge gate Declared tier, p0/p1, reviewers — must match markers
fix-queue.json Commander (after review) stop hook P0/P1 issues for fix rounds
critic-queue.json Commander (hyperplan) stop, advance-critic-queue Unresolved critic items
reports/debate-round-*.json Commander advance_critic_queue Non-empty claims required before accepted

Invariants (code-enforced)

  • New commit → new head_sha → old markers and verdict are stale; re-run required reviewers.
  • Markers must have source: cursor-subagentStop and a valid HMAC seal; hand-written JSON is rejected.
  • When config.active is false, most gates allow normal tooling (no active MAP session).

3. Hooks — record and consume state

Hooks are installed from hooks/hooks.json.template into the consumer's hooks.json. All MAP logic delegates to hooks/review_gate.py.

sequenceDiagram
    participant U as User / Commander
    participant C as Cursor Agent
    participant H as review_gate.py
    participant FS as .review/

    U->>C: New chat
    C->>H: sessionStart → session-resume
    H->>FS: read config + progress
    H-->>C: additional_context (resume phase, routing hints)

    U->>C: Task spawns subagent
    C->>H: subagentStart → set-role
    H->>FS: write roles/{id}.json, update progress.last_spawn

    C->>C: Subagent work (Write/Shell gated by check-tool-permission)
    C->>H: subagentStop → record-subagent
    H->>FS: write session/{branch}/{sha}/{type}.json + session-summary

    C->>H: stop → stop-check
    H->>FS: read fix / critic / security queues
    H-->>C: followup_message (next round hints)

    C->>H: gh pr merge / git push main
    H->>FS: validate_review_state
    H-->>C: allow or deny
Loading

Hook entry points

Event Command Role
beforeShellExecution check-merge Block gh pr merge, git push, GitHub merge API calls
preToolUse Shell check-tool-permission + check-merge Shell write-pattern block + merge double-check
preToolUse Task check-task-alignment When active, Task role must match workflow
preToolUse Write/Delete check-tool-permission Role-based path allowlist
subagentStart set-role Record logical_role (incl. reviewer inference for generalPurpose)
subagentStop record-subagent Write HMAC-sealed session marker
stop stop-check Inject followup when queues are non-empty at stop phase
sessionStart session-resume Inject resume context + routing recommendations
preCompact compact-inject Inject MAP state summary before context compaction
beforeMCPExecution check-mcp-permission Block write MCP tools for read-only roles

Secret for marker sealing: HOOKS_DIR/.review-gate-secret (or OMC_SECRET_FILE). See docs/security.md.

Threat model

MAP hooks run locally under a trusted single user on their machine. They enforce merge discipline inside Cursor sessions but do not replace GitHub branch protection, required status checks, or server-side review policies. Treat hooks as a developer aid; configure repository settings for team enforcement.

4. Workflows

Workflow IDs, phase lists, and merge-gate profiles are defined in WORKFLOW_PHASES, WORKFLOW_GATE_PROFILES, and WORKFLOW_STOP_PHASES in hooks/review_gate.py.

Skill Workflow ID Merge gate
multi-agent-pr multi-agent-pr Required
map-hyperplan map-hyperplan Blocked while active (planning-only)
map-security map-security Conditional (on if code outside report/poc changes)
map-refactor map-refactor Required + regression

Every workflow starts with a Configuration Gate: Commander runs AskQuestion, writes .review/config.json with active: true and .review/progress.json with phase: config-confirmed, then spawns subagents.

4.1 multi-agent-pr — feature development / PR

Use for: features, fixes, PRs that merge to main.

config-confirmed → spec-writing → architect-review → adjudication
  → coding → testing → review-pending → synthesis-complete → merge-ready → merged
Phase Business step State recorded
Configuration Gate AskQuestion → config.json + progress.phase=config-confirmed config, progress
Spec Commander writes .specs/prN-xxx.md spec file (may be committed)
Architect Task(architect) reviews spec → P0/P1/P2 roles/, architect marker
Adjudication Commander revises spec spec update
Coding Task(coder) implements + unit tests coder marker
Testing Task(tester-writer) integration/boundary tests tester marker
Review Parallel 3-engine reviewers (generalPurpose + logical_role: reviewer-*) 3 reviewer markers
Synthesis Commander dedupes → writes verdict.json (p0: 0, p1: 0) verdict.json
Fix round fix-queue.json → coder fixes → re-review → advance-fix-queue CLI fix-queue, progress
Merge gh pr merge hooks validate markers + verdict + tier

Tier requirements (validate_review_state):

Tier Reviewers required Coder required
Hotfix ≥ 1 reviewer-* Yes
Standard All 3: grok, codex, gemini Yes
Large All 3 Yes

Hook-inferred minimum tier from git diff can raise the declared tier; Commander cannot under-report.

Full playbook: skills/multi-agent-pr/SKILL.md

4.2 map-hyperplan — adversarial planning

Use for: spec review, design debate, architecture planning — no business code.

config-confirmed → draft → critics → debate → revise → accepted → merge-back-to-plan
Phase Business step State recorded
Configuration Gate workflow: map-hyperplan config, progress
Draft .specs/{name}.md (status: draft) spec; writes limited to .specs/, .review/
Critics Parallel architect / generalPurpose critics markers (no coder)
Debate reports/debate-round-N.json schema-validated debate JSON
Revise Update spec; open items → critic-queue.json critic-queue, phase=revise
Accepted advance-critic-queue clears queue Requires non-empty debate claims; phase=accepted; auto config.active=false
Merge-back Commander fuses P0/P1 into .cursor/plans/*.plan.md plan file (post-exit Commander step)
Build Switch to multi-agent-pr / coder new session

stop hook at phase=revise reads critic-queue and prompts revision.

Lifecycle doc: docs/workflows/plan-then-hyperplan.md · Skill: skills/map-hyperplan/SKILL.md

4.3 map-security — security audit

Use for: vulnerability hunt, security assessment, PoC verification.

config-confirmed → scope → hunt → triage → poc → report
Phase Business step State recorded
Scope Validate config.scope_paths config
Hunt 3 explore hunters (read-only) explore markers, roles/
Triage Dedupe by fingerprint report draft
PoC coder in .review/poc/ sandbox only poc marker; Write gated to poc dir
Report reports/security-{date}.md phase=report
Second hunt (optional) Unverified High+ → security-queue.json stop hook prompts at report phase

Merge gate is off for report-only work. If poc-fix modifies code outside .review/poc/ and .review/reports/, gate is forced on (hotfix tier + reviewer + verdict).

Skill: skills/map-security/SKILL.md

4.4 map-refactor — baseline + regression

Use for: module split, migration, rename with regression proof.

config-confirmed → analysis → baseline → implement → regression → review-pending → synthesis-complete → merge-ready → (merged | cleanup)
Phase Business step State recorded
Analysis / Baseline Architect analysis; run baseline_test_cmd reports/baseline-{sha}.json
Implement Task(coder) refactor coder marker
Regression Re-run same test command reports/regression-{sha}.json; flakes → quarantine-tests.json
Review + merge Same 3-engine review + verdict.json as multi-agent-pr markers + verdict 
python3 "$OMC_ROOT/hooks/review_gate.py" advance-fix-queue /path/to/repo [resolved-id,...] --increment-round

Skill: skills/map-refactor/SKILL.md · Commander steps overlap multi-agent-pr §8b.

5. Supporting capabilities

Capability Entry Purpose
Routing hints sessionStart → _routing_hints Suggest hyperplan / security / refactor from draft specs, GitHub security labels, TODO density
Routing rules routing-rules.json (optional, per repo) Keyword → workflow recommendations
Queue CLIs advance-fix-queue, advance-critic-queue Commander advances phase / clears queues after fix or critic cycles
Knowledge artifacts .review/knowledge/pr{N}/ Optional PR learnings archive (validated by validate_knowledge_artifacts)
Marker anti-forgery _seal_marker / _valid_marker_seal HMAC sealing; merge gate rejects manual marker JSON
Role permission matrix check_tool_permission_from_hook Reviewers read-only; architect → .specs/ + .review/; tester → tests/; poc → .review/poc/

6. Architecture overview

flowchart LR
    subgraph install["Install layer"]
        I[install.py / doctor]
    end

    subgraph workflows["Four workflows"]
        PR[multi-agent-pr]
        HP[map-hyperplan]
        SEC[map-security]
        REF[map-refactor]
    end

    subgraph gate["review_gate.py"]
        Phase[phase state machine]
        Perm[tool permissions]
        Merge[merge gate]
    end

    subgraph state[".review/ state"]
        CFG[config + progress]
        MK[session markers]
        VD[verdict]
        Q[queues + reports]
    end

    I --> workflows
    workflows --> CFG
    CFG --> Phase
    Phase --> Perm
    MK --> Merge
    VD --> Merge
    Q --> Phase
Loading

Code anchors: load_map_context, set_role_from_hook, record_subagent_from_hook, validate_review_state, check_merge_from_hook, stop_check_from_hook, advance_fix_queue, advance_critic_queue.

Further install and CI detail: docs/architecture.md

Documentation map

Doc Contents
docs/architecture.md Components, install targets, CI
CONTRIBUTING.md Clone, tests, MAP PR flow
SECURITY.md Vulnerability reporting
docs/install.md Install modes and manifest
docs/security.md Secret trust contract
docs/state-migration.md DEF-09 path migration
docs/workflows/plan-then-hyperplan.md Plan → hyperplan → merge-back
docs/integrations/issue-to-pr.md Consumer example
skills/multi-agent-pr/SKILL.md Full PR pipeline playbook
skills/map-hyperplan/SKILL.md Adversarial planning playbook
skills/map-security/SKILL.md Security audit playbook
skills/map-refactor/SKILL.md Refactor + regression playbook

Development

Zero-dep tests (stdlib only):

./hooks/run_tests.sh
./scripts/ci_check_stale_paths.sh

Full local CI mirror (pins from requirements-dev.txt: ruff, mypy, coverage):

./hooks/run_ci_local.sh

mypy in CI / run_ci_local.sh checks hooks/review_gate.py only (acceptable scope today; extend if scripts/ gains gate logic).

CI: .github/workflows/ci.yml — ruff, mypy, tests, coverage, compile check, install smoke, stale-path grep.

License

MIT — see LICENSE.

About

Independent MAP (Multi-Agent PR) engine for Cursor

Topics

ai-agentscursormerge-gatemulti-agent

Resources

Readme
MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages