Sidekick — AI Coding Agents for Claude Code and Codex

AI coding agents for Claude Code and Codex — Sidekick lets the active host AI delegate implementation to Forge, Kay, or Codex while the host stays focused on planning, review, mentoring, and communication.

Sidekicks

Sidekick	Activation surface	Agent	Status
Forge	/forge	ForgeCode — #7 Terminal-Bench 2.0 (81.8%)	✅ v0.6.2
Kay	kay-delegate	OSS Codex-lineage execution agent — Codex CLI #6 Terminal-Bench 2.0, kay exec, OpenCode Go provider routing, MiMo-V2.5-Pro for non-trivial work, MiMo-V2.5 for vision / visual reasoning, MiniMax M2.7 for trivial work, and DeepSeek V4 Flash for verification/reporting work	✅ v0.6.2
Codex	codex-delegate	Local OpenAI Codex CLI sidekick — codex exec, GPT-5.4 Mini, Extra High reasoning, workspace-write sandboxing, and never-ask approval policy injected by Sidekick	✅ v0.6.2

More sidekicks planned.

---

Docs

If you want the docs in the right order, start here:

• Start Here — task-first navigation
• Audience — who each doc is for
• Glossary — canonical terminology
• Compatibility — Claude Code, Codex, Forge, and Kay runtime differences
• ADR index — durable docs-system decisions

For help-site workflows, use the Help Center.

Installation

Install through the active host's plugin surface:

# Claude Code
/plugin install alo-labs/sidekick

# Codex
codex plugin marketplace add alo-labs/codex-plugins

After installation, runtime readiness is checked when you start Forge or Kay delegation for the current session.

---

Development Layout

Sidekick keeps host-agnostic workflow sources under skills/. Host-facing skill bundles are generated from that source tree:

skills/           Canonical Forge, Kay, and Codex workflow sources
agents/claude/    Generated Claude Code skill surface
agents/codex/     Generated Codex skill surface
scripts/          Host-surface renderer and maintenance helpers

Edit skills/ first, then run:

bash scripts/sync-host-surfaces.sh

The plugin manifests point at the generated host bundle for each runtime, while tests keep the generated bundles synchronized with the renderer.

---

Forge — ForgeCode Sidekick

What it does

• Auto-installs ForgeCode on first session start and checks readiness when Forge delegation starts for the current session
• Guides Forge provider setup for MiniMax Coding without putting provider keys in the prompt
• Turns the host into an orchestrator: Claude Code or Codex plans and communicates, while Forge executes file changes, tests, and commits
• Fallback ladder: automatic 3-level recovery on failure — L1 Guide (reframe), L2 Handhold (decompose), L3 Take over (sidekick forge-level3 start|stop, project-scoped direct work + DEBRIEF)
• AGENTS.md mentoring: after every task, the host AI extracts learnings and writes them to a 3-tier instruction store (~/forge/AGENTS.md, ./AGENTS.md, session logs) — delegation gets smarter over time
• Skill injection: 4 bootstrap skills (testing-strategy, code-review, security, quality-gates) auto-injected into task prompts based on task type
• Token optimization: task prompts capped at 2,000 tokens with validated .forge.toml compaction defaults

Kay — OSS Codex-Lineage Sidekick

What it does

• Auto-installs Kay from the pinned alo-labs/kay installer on first session start and keeps legacy code, codex, and coder aliases compatibility-only
• Activates Kay work through kay-delegate; active Kay mode launches kay exec --full-auto and Sidekick injects the OpenCode Go provider plus the task-appropriate model automatically
• Uses Kay's native agents, skills, subagents, and AGENTS.md support instead of recreating Forge-style prompt injection
• Supports Claude Code and Codex hosts by running Kay as a child execution process through the packaged kay-delegate skill
• Defaults to OpenCode Go at delegation time, with the model selected automatically from the task type
• Keeps a project-local audit index at .kay/conversations.idx; the canonical Kay workflows live in the delegate and stop skills, with the legacy flat alias preserved only as a hidden compatibility entry at skills/codex-delegate.md.

The website setup shortcuts /forge:delegate and /kay:delegate are shipped alias skills. They route to the canonical /forge and kay-delegate workflows.

Codex — OpenAI Codex CLI Sidekick

What it does

• Uses the local OpenAI Codex CLI as a child execution runtime instead of the OSS Kay runtime.
• Activates Codex work through codex-delegate; active Codex mode launches codex exec and Sidekick injects -m gpt-5.4-mini, -c model_reasoning_effort=xhigh, --sandbox workspace-write, and --ask-for-approval never.
• Rejects the legacy Kay codex compatibility alias when Codex mode is active; the real OpenAI Codex CLI must be on PATH.
• Keeps a project-local audit index at .codex/conversations.idx; the canonical Codex workflows live in skills/codex-delegate/SKILL.md and skills/codex-stop/SKILL.md.
• Supports both Claude Code and Codex hosts through the same host-neutral canonical skill source and generated host bundles.

Codex flow

You → Claude Code or Codex (plan + communicate) → Codex CLI (implement + commit) → host AI (review + report)

Host AI handles: architecture, explanations, research, code review Codex handles: writing files, features, tests, git commits

Kay flow

You → Claude Code or Codex (plan + communicate) → Kay (implement + commit) → host AI (review + report)

Host AI handles: architecture, explanations, research, code review Kay handles: writing files, features, tests, git commits

Forge flow

You → Claude Code or Codex (plan + communicate) → Forge (implement + commit) → host AI (review + report)

Host AI handles: architecture, explanations, research, code review Forge handles: writing files, features, tests, git commits

Forge provider setup

The host AI will guide you to:

1. Create MiniMax.io API access at https://platform.minimax.io/subscribe/token-plan.
2. Store the credential in Forge's native ~/forge/.credentials.json array format.
3. Point Forge at MiniMax M2.7 through ~/forge/.forge.toml.

The host configures Forge automatically and delegates coding work from that point.

Providers & Models

Provider	Model	Notes
OpenCode Go	MiMo-V2.5-Pro mimo-v2.5-pro	Main workhorse path for planning, implementation, reviewing, and other non-trivial tasks
OpenCode Go	MiMo-V2.5 mimo-v2.5	Vision / visual reasoning work that needs image, diagram, screenshot, or other multimodal input
OpenCode Go	MiniMax M2.7 minimax-m2.7	Trivial technical work
OpenCode Go	DeepSeek V4 Flash deepseek-v4-flash	Test running, issue reporting, and work completion verification, not review

---

Testing

tests/run_release.bash chains the strict non-live suites plus the live Forge/Kay install, smoke, E2E, and Kay marketplace-install gates.

Tier	Script	Runs without Forge/Kay	Purpose
Strict unit + integration	tests/run_unit.bash	✅	32 non-live suites — hook classifiers, generated host skill surfaces, idx audit, plugin integrity, docs contract, homepage/help-site navigation, social preview, post-release cleanup guard tests, clean reinstall bootstrap, runner contract, marketplace release-gate regressions, Kay wrapper isolation/proof promotion, and Forge/Kay coverage gaps. It does not delete developer artifacts; release cleanup is an explicit post-release step.
Skip-safe local sweep	tests/run_all.bash	✅	Delegates to run_unit.bash, then runs every live-gated wrapper in skip-safe mode: Forge E2E, Forge smoke/live E2E, Kay plugin/read, marketplace install, smoke, and live E2E.
Forge smoke	tests/smoke/run_smoke.bash	skip	forge --version + trivial forge -p round-trip against the real binary.
Forge live E2E	tests/run_live_e2e.bash	skip	Full host→Forge delegation on a seeded-buggy testapp (tests/testapp/) — proves the 5-field prompt shape, tool-use, and verification loop work end-to-end.
Kay marketplace install	tests/run_live_codex_marketplace_install.bash	skip	Installs Sidekick through the Codex marketplace path and verifies the installed Kay and Forge surfaces.
Kay smoke	tests/smoke/run_codex_smoke.bash	skip	kay --version + trivial kay exec round-trip against the real binary, with legacy names kept as compatibility aliases.
Kay live E2E	tests/run_live_codex_e2e.bash	skip	Full host→Kay delegation on the same seeded-buggy testapp — proves the 5-field prompt shape, edit, and verification loop work end-to-end.

The live stages are gated behind SIDEKICK_LIVE_FORGE=1 and SIDEKICK_LIVE_CODEX=1 so they never run in CI. CI runs the strict non-live runner. Before tagging a new version, run the Codex live release pyramid twice; add the Forge live flag when Forge provider testing is available:

bash tests/run_in_kay.bash SIDEKICK_LIVE_CODEX=1 bash tests/run_release.bash
bash tests/run_in_kay.bash SIDEKICK_LIVE_CODEX=1 bash tests/run_release.bash

To include optional Forge live stages when Forge provider testing is available, add SIDEKICK_LIVE_FORGE=1 to either run.

Local/pre-release test evidence must be produced inside Kay via tests/run_in_kay.bash. Kay test stages always force OpenCode Go with deepseek-v4-flash and low reasoning, even when normal delegation routing would select a different Kay model.

Before any release, make the final release-candidate commit first, then complete the 4-stage pre-release quality gate exactly as documented in site/pre-release-quality-gate.md (including each stage's own clean-pass loop), then run two current-session live release-pyramid passes. tests/run_release.bash writes isolated quality-gate-live-pyramid-candidate markers; only tests/run_in_kay.bash promotes successful canonical live runs to proof-bound final quality-gate-live-pyramid markers. Stage and live-pyramid markers are scoped to the current host session and current commit SHA; release operators must verify this evidence before publishing.

After the release is published, run bash tests/post_release_cleanup.bash so the local repo returns to a clean post-release state. This cleanup only removes transient build/cache artifacts; .planning/, site/specs, and site/design content stay in place.

Without those env vars run_release.bash still runs the strict non-live tier and cleanly skips the live tiers, but CI uses tests/run_unit.bash directly.

---

License

MIT — Ālo Labs