# @a5c-ai/babysitter-cursor

Babysitter orchestration plugin for [Cursor IDE](https://cursor.com) and
its headless CLI agent mode.

This package ships a complete Cursor plugin bundle -- skills, lifecycle
hooks, and SDK integration -- that lets you run Babysitter's event-sourced,
multi-step orchestration engine directly inside Cursor sessions. It uses the
Babysitter SDK CLI and the shared `~/.a5c` process-library state. The
installer registers the plugin bundle and materializes the active skills and
hooks so Cursor can execute Babysitter commands and hook scripts directly.

## Prerequisites

- **Node.js 22+**
- **Cursor IDE** with CLI agent support (`cursor` command available on PATH)
- **CURSOR_API_KEY** environment variable -- required for headless CLI mode
- **Babysitter SDK CLI** (`@a5c-ai/babysitter-sdk`) -- installed globally

## Installation

Install the Babysitter CLI once:

```bash
npm install -g @a5c-ai/babysitter
```

### Via Cursor Marketplace

Install through Cursor's marketplace UI using the repo-root
`/.cursor-plugin/marketplace.json` manifest:

1. Add this repository as a Cursor marketplace source
2. Open the marketplace entry named **a5c-ai**
3. Install the plugin named **babysitter**

### Via Babysitter harness install (recommended for automation)

Use the SDK helper for scriptable global or workspace installs. This resolves to `npx --yes @a5c-ai/babysitter-cursor install ...` under the hood:

```bash
# Global install
babysitter harness:install-plugin cursor

# Workspace install
babysitter harness:install-plugin cursor --workspace /path/to/repo
```

If the workspace does not already have an active process-library binding, the
installer bootstraps the shared global SDK process library automatically:

```bash
babysitter process-library:active --json
```

### Alternative Installation (development)

For local development or environments without marketplace access:

#### Via the published package installer

```bash
npx --yes @a5c-ai/babysitter-cursor install --global
npx --yes @a5c-ai/babysitter-cursor install --workspace /path/to/repo
```

#### From generated source

```bash
npm run generate:plugins
node artifacts/generated-plugins/cursor/bin/install.js
```

#### Manual installation

Copy the plugin directory to your local Cursor plugins path:

```bash
cp -r artifacts/generated-plugins/cursor ~/.cursor/plugins/local/babysitter-cursor
# Or symlink for faster iteration:
ln -s "$(pwd)/artifacts/generated-plugins/cursor" ~/.cursor/plugins/local/babysitter-cursor
```

## Uninstallation

```bash
babysitter-cursor uninstall
```

Or via npm:

```bash
npm uninstall -g @a5c-ai/babysitter-cursor
```

## Plugin Structure (Directory Layout)

```
artifacts/generated-plugins/cursor/
  .cursor-plugin/
    plugin.json              # Cursor plugin manifest (skills, commands, hooks, metadata)
  plugin.json                # Babysitter plugin manifest (skills dir, hooks path, metadata)
  hooks.json                 # Legacy/manual hook configuration
  hooks/
    hooks-cursor.json        # Cursor plugin hook configuration
    session-start.sh         # SessionStart lifecycle hook (bash)
    session-start.ps1        # SessionStart lifecycle hook (PowerShell)
    stop-hook.sh             # Stop hook -- orchestration loop driver (bash)
    stop-hook.ps1            # Stop hook -- orchestration loop driver (PowerShell)
  skills/
    babysit/SKILL.md         # Core orchestration skill
    call/SKILL.md            # Start a new run
    plan/SKILL.md            # Plan without executing
    resume/SKILL.md          # Resume an incomplete run
    doctor/SKILL.md          # Diagnose run health
    retrospect/SKILL.md      # Analyze completed runs
    observe/SKILL.md         # Observer dashboard
    assimilate/SKILL.md      # Assimilate external methodologies
    help/SKILL.md            # Help and documentation
    user-install/SKILL.md    # User setup
  bin/
    cli.js                   # CLI entry point (babysitter-cursor command)
    install.js               # Installation script
    install-shared.js        # Shared installation utilities
    uninstall.js             # Uninstallation script
  scripts/
    team-install.js          # Team-level installation
  versions.json              # SDK version pinning
  package.json               # npm package metadata
  .cursorrules               # Custom instructions for Cursor agent
  .gitignore
```

## Hook Configuration

The plugin declares lifecycle hooks in `hooks/hooks-cursor.json` using the version 1
format. Hook event names use camelCase (e.g., `sessionStart`, `stop`).

```json
{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "bash \"./hooks/session-start.sh\"",
        "powershell": "powershell -NoProfile -ExecutionPolicy Bypass -File \"./hooks/session-start.ps1\"",
        "timeoutSec": 30
      }
    ],
    "stop": [
      {
        "type": "command",
        "bash": "bash \"./hooks/stop-hook.sh\"",
        "powershell": "powershell -NoProfile -ExecutionPolicy Bypass -File \"./hooks/stop-hook.ps1\"",
        "loop_limit": null
      }
    ]
  }
}
```

Each hook entry specifies a `bash` and/or `powershell` command, a `type`
(currently always `"command"`), and optional parameters like `timeoutSec`
or `loop_limit`.

### Hook Format Details

- **version**: Must be `1`. Identifies the hooks schema version.
- **Event names**: Use camelCase (`sessionStart`, `stop`). Not snake_case,
  not PascalCase.
- **loop_limit**: Controls how many times the stop hook can re-inject
  continuation before the session is forced to end. Set to `null` for
  unlimited orchestration iterations (the default for this plugin).
- **Input**: Hooks receive JSON via stdin containing session context
  (including `conversation_id` for session identification).
- **Output**: Hooks emit JSON via stdout. The stop hook uses
  `{followup_message: "..."}` to auto-continue the orchestration loop.

## Available Skills

The plugin registers ten skills that surface as slash commands within
Cursor:

| Skill | Description |
|-------|-------------|
| `babysit` | Core entrypoint. Orchestrate `.a5c/runs/<runId>/` through iterative execution. Invoke when asked to babysit, orchestrate, or run a workflow. |
| `call` | Start a new orchestration run. Everything after `$call` becomes the initial Babysitter request. Always creates an interactive run. |
| `plan` | Design a process definition without executing it. Useful for reviewing or refining a workflow before committing to a run. |
| `resume` | Resume an incomplete or paused orchestration run from where it left off. |
| `doctor` | Diagnose run health -- journal integrity, state cache, effects, locks, sessions, logs, and disk usage. |
| `retrospect` | Analyze a completed run: results, process quality, and suggestions for process improvements and optimizations. |
| `observe` | Launch the real-time observer dashboard to watch active runs. |
| `assimilate` | Assimilate an external methodology, harness, or specification into Babysitter process definitions. |
| `help` | Show documentation for Babysitter command usage, processes, skills, agents, and methodologies. |
| `user-install` | Set up Babysitter for yourself -- installs dependencies, interviews you about preferences, and configures user-level defaults. |

## Usage Examples

### Interactive (Cursor IDE)

Open a Cursor session and invoke any skill as a slash command:

```text
$babysit run my-workflow
$call build and test the authentication module
$plan design a data migration pipeline
$resume
$doctor
```

### Headless CLI

Run Cursor in headless agent mode for fully automated orchestration. The
`CURSOR_API_KEY` environment variable must be set.

```bash
export CURSOR_API_KEY="your-api-key"

cursor agent -p -f --trust --approve-mcps \
  'Build and test the authentication module'
```

With a workspace directory:

```bash
cursor agent -p -f --trust --approve-mcps \
  --workspace /path/to/repo \
  'Refactor the payment service to use the new API'
```

**Headless CLI flags:**

| Flag | Description |
|------|-------------|
| `-p` | Print mode (output to stdout) |
| `-f` | Non-interactive / force mode |
| `--trust` | Trust the workspace (skip confirmation prompts) |
| `--approve-mcps` | Auto-approve MCP server connections |
| `--workspace <dir>` | Set the working directory |

**Note:** The `afterAgentResponse` and `afterAgentThought` hook events do
NOT fire in CLI headless mode. The plugin relies on `sessionStart` and
`stop` hooks, which are supported in both interactive and headless modes.

## Orchestration Model

The plugin drives multi-step orchestration through a stop-hook loop
pattern. This is how Babysitter iterates autonomously within Cursor:

### SessionStart

Fires when a new Cursor session begins. The hook:

1. Checks and installs the required SDK version (pinned in `versions.json`)
2. Initializes a Babysitter session for the active Cursor session
3. The session ID is extracted from `conversation_id` in the hook's stdin
   JSON (not from an environment variable)

### Stop (Orchestration Loop Driver)

When Cursor attempts to end its turn, this hook intercepts the exit and:

1. Checks whether the active run has completed or emitted a completion proof
2. If the run is still in progress, emits `{followup_message: "..."}` to
   auto-continue the orchestration loop with the next iteration step
3. Only allows the session to exit when the run finishes or reaches a
   breakpoint requiring human input

This is what keeps Babysitter iterating autonomously -- each turn performs
one orchestration phase, and the stop hook decides whether to loop or yield.
The `loop_limit: null` setting in `hooks/hooks-cursor.json` allows unlimited iterations.

**Important:** The stop hook uses `{followup_message: "..."}` to signal
continuation, NOT `{decision: "block"}`. This is a Cursor-specific
convention.

## Configuration

### .cursorrules

The plugin includes a `.cursorrules` file for custom agent instructions.
This file is discovered by Cursor by convention and configures agent
behavior within sessions.

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CURSOR_API_KEY` | -- | API key for headless CLI mode (required) |
| `CURSOR_PLUGIN_ROOT` | Plugin directory | Plugin root directory |
| `BABYSITTER_STATE_DIR` | `<cwd>/.a5c` | State directory for session data |
| `BABYSITTER_LOG_DIR` | `~/.a5c/logs` | Log output directory override; default is the user-global Babysitter log root |

### SDK Version Pinning

The plugin pins its required SDK version in `versions.json`. The
SessionStart hook reads this file and ensures the correct version of
`@a5c-ai/babysitter-sdk` is installed globally before proceeding.

## Marketplace Distribution

Cursor Marketplace is Git-based. Plugins are distributed through Git
repositories that contain a manifest file.

### Plugin Manifest

The Cursor marketplace manifest lives at `.cursor-plugin/plugin.json`:

```json
{
  "name": "babysitter",
  "version": "0.1.0",
  "description": "Babysitter orchestration plugin for Cursor IDE/CLI ...",
  "author": {
    "name": "a5c.ai",
    "email": "support@a5c.ai",
    "url": "https://github.com/a5c-ai/babysitter"
  },
  "homepage": "https://github.com/a5c-ai/babysitter/tree/main/plugins/babysitter-unified/per-harness/cursor#readme",
  "repository": "https://github.com/a5c-ai/babysitter",
  "license": "MIT",
  "skills": "skills/",
  "hooks": "hooks/hooks-cursor.json"
}
```

The `skills` field points to the skills directory where Cursor
auto-discovers `SKILL.md` files in subdirectories. The `hooks` field
references the `hooks/hooks-cursor.json` configuration file.

### Marketplace Manifest

The repo-root Cursor marketplace manifest lives at `/.cursor-plugin/marketplace.json`:

```json
{
  "name": "a5c-ai",
  "owner": {
    "name": "a5c-ai",
    "email": "support@a5c.ai"
  },
  "metadata": {
    "description": "Babysitter orchestration plugins",
    "pluginRoot": "plugins"
  },
  "plugins": [
    {
      "name": "babysitter",
      "description": "Multi-step workflow orchestration for Cursor IDE",
      "version": "0.1.0",
      "source": "babysitter-cursor"
    }
  ]
}
```

### User Commands

```bash
babysitter harness:install-plugin cursor
```

## Troubleshooting

### Hook not firing

Run the doctor skill from within a Cursor session to diagnose hook and
session health:

```text
$doctor
```

Also check log output in `${BABYSITTER_LOG_DIR:-$HOME/.a5c/logs}/`:

- `babysitter-session-start-hook.log`
- `babysitter-stop-hook.log`
- `babysitter-stop-hook-stderr.log`
- `babysitter-session-start-hook-stderr.log`

- `$HOME/.a5c/logs/` and relevant logs and run/session specific logs there


### Run stuck or not progressing

Check the run status and diagnose:

```text
$doctor [run-id]
```

Or inspect the run directory directly:

```bash
babysitter run:status --run-id <runId> --json
babysitter run:events --run-id <runId> --json
```

### SDK version mismatch

If the plugin reports version incompatibility, ensure the pinned SDK
version is installed:

```bash
SDK_VERSION=$(node -e "console.log(JSON.parse(require('fs').readFileSync('versions.json','utf8')).sdkVersion)")
npm install -g @a5c-ai/babysitter-sdk@$SDK_VERSION
```

### Headless mode not working

Verify that `CURSOR_API_KEY` is set:

```bash
echo $CURSOR_API_KEY
```

Ensure the `cursor` CLI is available on PATH:

```bash
cursor --version
```

### afterAgentResponse / afterAgentThought hooks not firing

These hook events do not fire in CLI headless mode. This is expected
Cursor behavior. The plugin is designed to work with `sessionStart` and
`stop` hooks only, which are supported in both interactive and headless
modes.

### Windows limitations

On native Windows, hook execution depends on shell configuration. The
plugin includes both `bash` (.sh) and `powershell` (.ps1) hook scripts
to maximize compatibility. If hooks do not fire, try running from Git Bash
or WSL. The Cursor hook manifest includes explicit `powershell` entries alongside
`bash` entries for Windows PowerShell execution support.

## Development / Contributing

### Local development

```bash
git clone https://github.com/a5c-ai/babysitter.git
cd babysitter
npm install
npm run generate:plugins
node bin/install.js
```

### Publishing

```bash
cd artifacts/generated-plugins/cursor
npm run deploy            # Publish to npm (public)
npm run deploy:staging    # Publish to npm with staging tag
```

### Team installation

```bash
cd artifacts/generated-plugins/cursor
npm run team:install
```

This sets up the plugin for all team members in a shared workspace,
writing team-level configuration to `.a5c/team/`.

### Verification

Verify the installed plugin bundle:

```bash
npm ls -g @a5c-ai/babysitter-cursor --depth=0
```

Verify the active shared process-library binding:

```bash
babysitter process-library:active --json
```

## License

MIT