// Use when a Hermes Kanban worker wants to run Codex CLI as an isolated implementation lane while Hermes keeps ownership of task lifecycle, reconciliation, testing, and handoff.
Configure, extend, or contribute to Hermes Agent.
Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python.
Pitfalls, examples, and edge cases for Hermes Kanban workers. The lifecycle itself is auto-injected into every worker's system prompt as KANBAN_GUIDANCE (from agent/prompt_builder.py); this skill is what you load when you want deeper detail on specific scenarios.
Article illustrations: type × style × palette consistency.
Zero-install localhost tunnels over SSH via Pinggy.
Notion API + ntn CLI: pages, databases, markdown, Workers.
| name | kanban-codex-lane |
| description | Use when a Hermes Kanban worker wants to run Codex CLI as an isolated implementation lane while Hermes keeps ownership of task lifecycle, reconciliation, testing, and handoff. |
| version | 1.0.0 |
| author | Hermes Agent |
| license | MIT |
| metadata | {"hermes":{"tags":["kanban","codex","worktrees","autonomous-agents","prediction-market-bot"],"related_skills":["kanban-worker","codex","hermes-agent"]}} |
This skill defines the lightweight Hermes+Codex dual-lane convention for Kanban workers. Hermes is always the task owner: it calls kanban_show, decides whether Codex is appropriate, creates or selects an isolated workspace, starts and monitors Codex, reconciles any diff, runs verification, and writes the final kanban_complete or kanban_block handoff. Codex is an input lane only. Codex output is not a task completion signal, not a trusted reviewer, and not allowed to write durable Kanban state directly.
The convention exists so a Hermes worker can use Codex for bounded implementation help without changing the dispatcher. The dispatcher must still spawn Hermes workers. A worker may optionally spawn Codex inside its own run, then accept, partially accept, or reject the lane after independent review and tests.
Use the Codex lane when all of these are true:
Do not use the Codex lane when any of these are true:
kanban_complete, kanban_block, kanban_create, gateway messaging, or any Hermes board CLI as a substitute for the worker.Never run Codex directly in a shared dirty checkout. Use a branch/worktree name that ties the lane to the Kanban task and keeps untrusted edits isolated.
Recommended variables:
TASK_ID="${HERMES_KANBAN_TASK:-t_manual}"
REPO="/path/to/repo"
BASE="$(git -C "$REPO" rev-parse --abbrev-ref HEAD)"
SAFE_TASK="$(printf '%s' "$TASK_ID" | tr -cd '[:alnum:]_-')"
BRANCH="codex/${SAFE_TASK}/$(date -u +%Y%m%d%H%M%S)"
WORKTREE="/tmp/${SAFE_TASK}-codex-lane"
Create the isolated lane:
git -C "$REPO" fetch --all --prune
git -C "$REPO" worktree add -b "$BRANCH" "$WORKTREE" "$BASE"
git -C "$WORKTREE" status --short --branch
If the current Kanban workspace is already an isolated git worktree created for this task, you may create a sibling Codex branch inside it only if git status --short is clean except for intentional Hermes edits. Otherwise create a separate temporary worktree and cherry-pick or copy accepted commits back after reconciliation.
Cleanup after reconciliation:
git -C "$REPO" worktree remove "$WORKTREE"
git -C "$REPO" branch -D "$BRANCH" # only after accepted commits were copied/cherry-picked or intentionally rejected
Keep the worktree if it is needed as an artifact for review; record it in codex_lane.artifacts and mention it in the handoff.
Run these before spawning Codex. Missing Codex is a normal reason to skip the lane, not a task blocker if Hermes can do the task directly.
command -v codex
codex --version
codex features list | grep -i goals || true
If /goal support is required, enable or launch with the feature flag only after checking availability:
codex features enable goals || true
codex --enable goals --version
Authentication can be via OPENAI_API_KEY or the Codex CLI OAuth state (often ~/.codex/auth.json). Do not print token files. A missing OPENAI_API_KEY is not proof that auth is unavailable.
Use codex exec for bounded one-shot edits where Codex should exit on its own:
terminal(
command="codex exec --full-auto '$(cat /tmp/codex_prompt.md)'",
workdir=WORKTREE,
background=True,
pty=True,
notify_on_complete=True,
)
Use Codex /goal only for broader multi-step work that benefits from durable objective tracking. Launch interactively in a PTY/tmux session or with codex --enable goals if the feature is disabled by default. Keep the goal objective self-contained: repo path, task id, safety constraints, allowed scope, acceptance criteria, tests, and commit expectations.
Example /goal objective text to paste into Codex:
/goal Work in this repository only: <WORKTREE>. Task: <TASK_ID> <TITLE>.
Hermes owns the Kanban lifecycle; do not call Hermes kanban tools or messaging.
Create small commits on branch <BRANCH>. Follow the PMB safety constraints in the prompt.
Run the requested verification commands and report exact outputs. Stop after producing a diff and summary.
Do not use --yolo for prediction-market-bot or safety-sensitive repos. Prefer --full-auto inside the isolated worktree, then rely on Hermes reconciliation.
Use the linked template at templates/pmb-codex-lane-prompt.md for prediction-market-bot work. For other repos, keep the same structure and replace the PMB-specific safety block with repo-specific invariants.
Every Codex prompt must include:
task_id, title, and full Kanban acceptance criteria.For PMB, include these mandatory safety constraints verbatim:
PMB safety constraints:
- live-SIM is paper-only; do not add or enable live REST order entry.
- Never use market orders.
- Do not add execution crossing or bypass price/risk checks.
- Do not fake passive fills, fills, PnL, order states, or reconciliation evidence.
- Do not weaken risk gates, limits, kill switches, or fail-closed behavior.
- Keep research/selection outside the C++ hot path unless explicitly requested.
- Do not read, print, write, or require secrets/tokens/credentials.
Start long Codex lanes in the background with PTY and completion notification:
result = terminal(
command="codex exec --full-auto '$(cat /tmp/codex_prompt.md)'",
workdir=WORKTREE,
background=True,
pty=True,
notify_on_complete=True,
)
session_id = result["session_id"]
Monitor without interfering:
process(action="poll", session_id=session_id)
process(action="log", session_id=session_id, limit=200)
process(action="wait", session_id=session_id, timeout=300)
Send a Kanban heartbeat every few minutes for lanes longer than two minutes, e.g. kanban_heartbeat(note="Codex lane running in <WORKTREE>; waiting for tests/diff").
Kill conditions:
Kill command:
process(action="kill", session_id=session_id)
After kill, inspect git status --short, preserve useful patches only if safe, and record codex_lane.result: timed_out or rejected with a concrete rejected_reason.
Hermes must perform this checklist before accepting any Codex lane result:
git -C <WORKTREE> status --short --branch shows only expected files.git -C <WORKTREE> diff --stat and git diff were reviewed by Hermes.scripts/run_tests.sh for Hermes Agent or the repo's documented wrapper for other repos.Acceptance outcomes:
accepted: Codex diff/commits were reviewed, applied, and verified.partial: Some Codex work was accepted after edits or cherry-picks; rejected parts are documented.rejected: No Codex changes were accepted; reason is documented.timed_out: Codex exceeded the lane budget; useful artifacts may or may not exist.Include this object under metadata.codex_lane for every task where the lane was considered. If Codex was not used, set used: false and explain why in rejected_reason or a sibling notes field.
{
"codex_lane": {
"used": true,
"mode": "exec | goal | skipped",
"worktree": "/absolute/path/to/codex/worktree",
"branch": "codex/t_caa69668/20260508100000",
"command": "codex exec --full-auto ...",
"result": "accepted | rejected | partial | timed_out",
"accepted_commits": ["<sha1>", "<sha2>"],
"rejected_reason": "empty when fully accepted; otherwise concrete reason",
"tests_run": [
{"command": "scripts/run_tests.sh tests/tools/test_x.py", "exit_code": 0, "owner": "hermes"},
{"command": "codex-reported: npm test", "exit_code": 0, "owner": "codex"}
],
"artifacts": ["/absolute/path/to/log-or-patch"]
}
}
For tasks that intentionally skip Codex:
{
"codex_lane": {
"used": false,
"mode": "skipped",
"worktree": null,
"branch": null,
"command": null,
"result": "rejected",
"accepted_commits": [],
"rejected_reason": "Direct Hermes edit was smaller and safer than spawning Codex.",
"tests_run": [],
"artifacts": []
}
}
/goal for quick edits. Prefer codex exec unless durable multi-step continuation is needed.rejected_reason must explain the decision.command -v codex, codex --version, and optional goals feature checks.git diff and safety-sensitive files.kanban_complete.metadata.codex_lane follows the schema above.