Every current activation command, hook, runtime command, session marker, test command, and canonical term — all in one place. If you need the vocabulary first, read Glossary and Compatibility.
| Command | Description |
|---|---|
| /sidekick:kay-delegate | Activate Kay sidekick mode for the current session and route implementation through kay exec. |
| /sidekick:kay-delegate xiaomi | Activate Kay mode with Xiaomi routing for the session. |
| /sidekick:kay-delegate ocg | Activate Kay mode with OpenCode Go routing for the session. |
| /sidekick:kay-stop | Deactivate Kay sidekick mode and clear the Kay session marker. |
| /sidekick:codex-delegate | Activate Codex sidekick mode for the current session and route implementation through local codex exec. |
| /sidekick:codex-stop | Deactivate Codex sidekick mode and clear the Codex session marker. |
Sidekick ships PreToolUse and PostToolUse hooks. They stay dormant until a user explicitly starts Kay or Codex delegation for the current session. The shared active-sidekick selector is a mutual-exclusion gate: it must point at kay or codex before matching hooks enforce delegation behavior.
| Hook | Event | Description |
|---|---|---|
codex-delegation-enforcer.sh | PreToolUse (Write / Edit / NotebookEdit / Bash) | Denies direct implementation edits while Kay or Codex mode is active, rewrites supported runtime commands, and records audit metadata. |
codex-progress-surface.sh | PostToolUse (Bash) | Parses Kay or Codex subprocess output, strips terminal controls, redacts obvious secrets, and emits compact progress summaries. |
Start Kay mode through /sidekick:kay-delegate. These lower-level runtime commands are what active Kay mode uses after activation:
| Command | Purpose |
|---|---|
| kay exec "<task>" | Native Kay runtime command used after Kay mode is active. |
| kay login --provider opencode-go --with-api-key | Configure OpenCode Go credentials for the Kay provider path. |
| SIDEKICK_KAY_PROVIDER | Environment override for Kay provider routing. |
After activation, Sidekick routes child implementation work through the selected runtime:
| Sidekick | Child command | Managed contract |
|---|---|---|
| Kay | kay exec | Provider selected by default routing, xiaomi, ocg, or SIDEKICK_KAY_PROVIDER. |
| Codex | codex exec | gpt-5.4-mini, model_reasoning_effort=xhigh, workspace-write, --ask-for-approval never. |
Sidekick uses session markers so hooks enforce only after explicit activation.
| Path | Purpose |
|---|---|
~/.sidekick/sessions/<session>/active-sidekick | Contains kay or codex; only one sidekick is active per host session. |
.kay/sessions/<session>/.kay-delegation-active | Kay mode marker. |
.codex/sessions/<session>/.codex-delegation-active | Codex mode marker. |
.kay/conversations.idx | Project-local Kay audit ledger. |
.codex/conversations.idx | Project-local Codex audit ledger. |
Current strict and release checks:
| Command | Purpose |
|---|---|
bash tests/run_unit.bash | Strict non-live unit and integration suites. |
bash tests/run_all.bash | Skip-safe aggregate suite. |
bash tests/run_in_kay.bash SIDEKICK_LIVE_CODEX=1 bash tests/run_release.bash | Kay-hosted live release gate. |
Sidekick surfaces bounded, redacted progress output from child runtimes. The host treats these summaries as useful context, not proof of completion.
| Field | Description |
|---|---|
| [KAY] | Bounded Kay subprocess output while Kay mode is active. |
| [KAY-SUMMARY] | Compact Kay status block when Kay emits structured progress. |
| [CODEX] | Bounded Codex subprocess output while Codex mode is active. |
| [CODEX-SUMMARY] | Compact Codex status block when Codex emits structured progress. |
Project-level AGENTS.md remains the instruction surface for hosts and sidekicks. It should describe supported sidekicks, project conventions, generated surfaces, tests, integrity workflow, and release discipline.
Files created and managed by Sidekick:
| Path | Purpose |
|---|---|
| skills/kay-delegate/SKILL.md | Canonical Kay delegate workflow and runtime guidance |
| skills/kay-stop/SKILL.md | Canonical Kay stop workflow |
| skills/codex-delegate/SKILL.md | Canonical Codex delegate workflow and runtime guidance |
| skills/codex-stop/SKILL.md | Canonical Codex stop workflow |
~/.sidekick/sessions/<session>/active-sidekick | Shared selector containing kay or codex |
| .kay/sessions/<session>/.kay-delegation-active | Kay state marker used by Kay hooks when Kay mode is active |
| .codex/sessions/<session>/.codex-delegation-active | Codex state marker used by Codex hooks when Codex mode is active |
| .kay/conversations.idx | Project-local Kay task lookup ledger |
| .codex/conversations.idx | Project-local Codex task lookup ledger |
| AGENTS.md | Project-level host and sidekick instructions |