Set Up Codex for Spec Kitty
Who is this for (1)
- Stakeholder Persona: Project Owner — Written for the Project Owner reader.
Codex CLI uses Spec Kitty’s project-local agent skills. Spec Kitty installs one
skill package per command under .agents/skills/spec-kitty-<command>/SKILL.md.
Use this guide when an existing project does not show $spec-kitty-* skills in
Codex, or when you want a small launcher that enters the repo and activates the
local Python environment before starting Codex.
Prerequisites
- You are working in the
spec-kittyrepository root. codexis installed and available on yourPATH.- Spec Kitty has been initialized or synced for Codex:
spec-kitty init --ai codex# or, for an existing projectspec-kitty agent config add codexspec-kitty agent config syncVerify the skill packages
Confirm the generated skills exist:
ls .agents/skills/ls .agents/skills/spec-kitty-specify/SKILL.mdCodex should expose these as $spec-kitty-<command> skills, for example:
$spec-kitty-specify$spec-kitty-plan$spec-kitty-tasks$spec-kitty-implementIf the packages are missing, regenerate them:
spec-kitty agent config syncOptional launcher
Create scripts/tool_configs/kitty-cdx.sh:
#!/usr/bin/env bashset -euo pipefail
SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"REPO_ROOT="$(cd -- "${SCRIPT_DIR}/../.." && pwd)"
CODEX_BIN="$(type -P codex || true)"if [[ -z "${CODEX_BIN}" ]]; then echo "codex executable was not found in PATH" >&2 exit 127fi
cd "${REPO_ROOT}"
if [[ -f ".venv/bin/activate" ]]; then set +u . ".venv/bin/activate" set -ufi
exec "${CODEX_BIN}" "$@"Make it executable:
chmod +x scripts/tool_configs/kitty-cdx.shAdd a shell alias:
alias kitty_cdx='/path/to/spec-kitty/scripts/tool_configs/kitty-cdx.sh'Windows launcher
Create scripts/tool_configs/kitty-cdx.ps1:
$ErrorActionPreference = "Stop"
$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path$RepoRoot = Resolve-Path (Join-Path $ScriptDir "..\..")
$CodexCommand = Get-Command codex -CommandType Application -ErrorAction Stop$CodexPath = $CodexCommand.Source
Set-Location $RepoRoot
$activate = Join-Path $RepoRoot ".venv\Scripts\Activate.ps1"if (Test-Path $activate) { . $activate}
& $CodexPath @argsAdd a kitty_cdx function in your PowerShell profile:
function kitty_cdx { & "C:\path\to\spec-kitty\scripts\tool_configs\kitty-cdx.ps1" @args}Reload your profile:
. $PROFILETroubleshooting
- Codex does not show
$spec-kitty-*skills. Runspec-kitty agent config sync, confirm.agents/skills/spec-kitty-*/SKILL.mdexists, and restart Codex. - Only old prompt-style commands appear.
Refresh the project with
spec-kitty upgrade --projectand re-runspec-kitty agent config sync. - Launcher cannot find
codex. Install Codex CLI or put its binary onPATH, then re-runkitty_cdx.