sidekick

Sidekick

AI coding-agent delegation for Claude Code, Codex, and Cursor.

Sidekick lets the host AI stay focused on planning, review, mentoring, and communication while supported sidekicks perform bounded implementation work. The host creates the plan, delegates tasks, reviews sidekick output, and verifies results before reporting completion.

Plain version: install Sidekick on your host, activate Kay or Codex for the current session, delegate implementation, then let the host prove the work is actually done.

Docs: sidekick.alolabs.dev · Cursor marketplace: alo-labs/alo-labs-cursor-marketplace · Releases: github.com/alo-exp/sidekick/releases

What Sidekick Adds

Area	Sidekick owns
Delegation	Kay (kay exec) and Codex (codex exec) sidekick workflows
Host role	Planning, review, verification, and communication stay with the host
Enforcement	PreToolUse hooks block direct host edits while a sidekick is active
Progress	Bounded, redacted Kay/Codex output surfaces through PostToolUse hooks
Session state	Per-host active-sidekick marker and audit indexes under .kay / .codex

How It Works

Host AI = Brain
Sidekick = Hands

1. The host prepares a focused implementation prompt with files, constraints, and success criteria.
2. The active sidekick writes files and runs commands through its child runtime.
3. Sidekick hooks keep the host from bypassing the active sidekick mid-task.
4. The host verifies the result against the original prompt, integration points, and required tests.
5. If verification fails, the host relaunches the active sidekick with correction context until the failure is resolved.

Sidekick does not install SessionStart hooks. Kay and Codex readiness is checked when delegation starts for the current session.

Supported Sidekicks

Sidekick	Activate	Stop	Runtime
Kay	/sidekick:kay-delegate	/sidekick:kay-stop	Kay runtime via kay exec
Codex	/sidekick:codex-delegate	/sidekick:codex-stop	Local OpenAI Codex CLI (gpt-5.4-mini, extra-high reasoning)

Kay defaults to existing opencode-go routing. Use /sidekick:kay-delegate xiaomi for Xiaomi routing, /sidekick:kay-delegate ocg to force OpenCode Go routing, or SIDEKICK_KAY_PROVIDER as an environment override. Sidekick selects the model automatically per provider.

On Cursor, the same workflows appear as slash commands kay-delegate, kay-stop, codex-delegate, and codex-stop.

Quick Start

Claude Code

/plugin install alo-labs/sidekick

Restart Claude Code, then activate a sidekick:

/sidekick:kay-delegate
/sidekick:codex-delegate

Codex host

codex plugin marketplace add alo-labs/codex-plugins

Install Sidekick from that marketplace, restart Codex, then run /sidekick:kay-delegate or /sidekick:codex-delegate.

Cursor (recommended)

Cursor discovers plugins through registered marketplaces, not from files copied into ~/.cursor/plugins/cache/.

1. In Cursor, open Settings → Plugins → Add marketplace.
2. Add source https://github.com/alo-labs/alo-labs-cursor-marketplace.
3. Install sidekick (currently v0.8.1, commit-pinned in the marketplace catalog).
4. Developer: Reload Window so hooks/cursor-hooks.json loads before delegation.
5. Enable the plugin if needed, reload again, then merge hooks:

bash scripts/install-cursor.sh --merge-hooks-only

Use slash commands kay-delegate, codex-delegate, kay-stop, and codex-stop in agent chat.

Development from a checkout:

bash scripts/install-cursor.sh --merge-hooks

This syncs generated agents/cursor/ bundles, copies the plugin into ~/.cursor/plugins/cache/alo-labs/sidekick/<version>, registers a local marketplace symlink, and optionally merges hooks into ~/.cursor/hooks.json.

Hook Safety

Sidekick hooks are designed to stay out of the way until delegation is active.

State	Behavior
Inactive	Enforcement hooks pass through with {"permission":"allow"} on Cursor and do not block unrelated host tools.
Active	PreToolUse hooks deny direct host edits; implementation must go through kay exec or codex exec.
Cursor merge	scripts/merge-cursor-hooks.py idempotently merges Sidekick entries into ~/.cursor/hooks.json, removes stale Sidekick hook paths, and stabilizes install paths via a current symlink.