igamenovoer/codex-cli-invoke-persist

Codex CLI Invoke Persist

Manual invocation

Invoke this skill explicitly by name ($codex-cli-invoke-persist) because it may execute the codex CLI. Do not invoke it implicitly from a generic request for Codex help.

Codex wrappers

Users may provide Codex wrappers with any name. They are often named codex-<something>, but they do not need to be.

• If the wrapper is an executable command or script such as .sh, .bat, .cmd, or a normal binary on PATH, pass it via --codex-cmd "<wrapper command...>" or CODEX_CMD.
• If the wrapper is a POSIX alias/function or a PowerShell function, use shell-launch mode: pass the wrapper name via --codex-cmd, add --codex-shell posix|powershell, and usually pass profile/setup code via --codex-shell-init. Optionally override the launcher with --codex-shell-cmd.
• The wrapper must accept the codex exec / codex exec resume flags used here, especially --json, -o/--output-last-message, --model, and the resume selector.

Heartbeats and deadlines

• For long-running work, prefer streaming (resume-stream) so stdout emits a steady JSONL heartbeat from codex exec resume --json.
• Do not add timeouts or terminate the Codex process while it is still working unless one of these applies: (1) the user explicitly requested a deadline, (2) the process is clearly stalled, or (3) the process is in a hard error state. If a deadline is requested, pass --deadline-seconds to the helper.
• Do not interrupt simply because intermediate output appears sufficient. Let Codex run to normal completion and evaluate the final result afterward.
• resume-json uses Codex JSONL internally, but the helper emits one final JSON object on stdout instead of forwarding the heartbeat stream.

Example triggers (user intent -> stage)

The skill itself is triggered by name, but once invoked, pick a stage based on user intent:

• Create/persist a new session (creation stage):
  • "Create a Codex session named review-src"
  • "Start a new Codex chat and save it as issue-1234"
  • "Make a new persistent Codex CLI session (session name: plan-feature-x)"
  • "Create a session named perf-review using role definition roles/perf_reviewer.md"
• Resume/call an existing session (invocation stage):
  • "Resume session review-src and ask: summarize the repo"
  • "Continue last chat"
  • "Use this thread_id and continue: <thread_id>"
• List existing sessions (listing stage):
  • "List my saved Codex sessions for this workspace"
  • "Show available session names"
  • "List sessions for workspace /abs/path/to/other/workspace"
• Delete saved sessions (deletion stage):
  • "Delete session name review-src"
  • "Remove saved Codex session review-src from this workspace"
  • "Delete all saved Codex sessions for this workspace"

Stages (sub-skills)

• Creation (create-session)

  • Required input: session name (the user may call it a "session alias")
  • Optional input:
    • Role definition .md: --role-definition-md /abs/path/to/role.md Codex CLI has no --append-system-prompt, so the helper prepends the file contents to the initial user prompt.
    • Model: --model ... (stored as last_model for later resumes)
    • Wrapper command: --codex-cmd "..." / CODEX_CMD
    • Shell-launch mode for alias/function wrappers: --codex-shell posix|powershell, usually with --codex-shell-init "..." / CODEX_SHELL_INIT, and optionally with --codex-shell-cmd "..." / CODEX_SHELL_CMD
    • Deadline: --deadline-seconds ... only when the user explicitly requested a time limit
    • Exec pass-throughs supported by the helper: --config, --enable, --disable, --image, --full-auto, --dangerously-bypass-approvals-and-sandbox, --skip-git-repo-check
  • Files touched:
    • Reads: role definition .md (if provided)
    • Writes: workspace mapping JSON (safe writes may create .bad.<pid> and .tmp.<pid>)
  • Keywords: "create session", "start new chat", "save as <name>"

• Invocation (resolve, resume-json, resume-stream)

  • Required input: prompt plus thread_id/session_id or session name
  • Behavior:
    • Resolves session name via the workspace mapping JSON unless a direct thread_id is provided
    • Runs codex exec resume <thread_id> --json
    • Defaults --model from stored last_model when not explicitly provided
    • Persists the effective model as the new last_model after a successful call
    • Supports --role-definition-md by prepending the file contents to the resumed prompt for that call
    • Lets the Codex process run to natural completion unless deadline/stall/error criteria are met
  • Deadlines: support --deadline-seconds only when the user explicitly requested a time limit
  • Keywords: "continue latest chat", "continue last chat", "resume session"

• Listing (list-sessions)

  • Required input: none (defaults to current workspace)
  • Optional input: workspace dir or explicit mapping file
  • Behavior: reads the workspace mapping JSON and returns an empty list if it does not exist yet
  • Keywords: "list sessions", "show session names"

• Deletion (delete-session, delete-all-sessions)

  • Required input: either thread_id/session_id or session name, or explicit "all sessions"
  • Optional input: workspace dir or explicit mapping file
  • Behavior: removes entries from the workspace mapping JSON or deletes the mapping file entirely; does not call codex
  • Keywords: "delete session", "remove saved session", "clear all sessions"

• Management file (session mapping JSON): <system-tmp>/agent-sessions/<workspace-basename>-<md5(abs-workspace-dir)>/codex-cli-alias-mapping.json (override with --mapping-file).

Workflow decision

• Create a new persistent session: follow references/creation.md.
• Resume an existing session: follow references/invocation.md.
• List existing sessions for a workspace: follow references/listing.md.
• Delete saved sessions: follow references/deletion.md.

Naming and selection rules

• Prefer the user's session name.
• If the user provides a thread_id or session_id, always use it as the resume target.
• If the user says "continue latest chat", "continue last chat", or similar, reuse the most recently referenced thread_id or session name in this conversation. If none exists, ask which session to use.

Model persistence

• The manifest stores last_model per session name.
• On reuse: if the user does not specify --model, use the stored last_model for that session name when present.
• On override: if the user explicitly specifies --model, use it for this call and persist it as the new default for next time.

Codex-specific limitations

• codex exec resume supports fewer flags than codex exec, so this helper intentionally persists only last_model, not broader exec-only options.
• Codex CLI has no Claude-style --append-system-prompt, so role definitions are prepended to the prompt text rather than attached as a separate system-prompt layer.
• resume-json is helper-generated JSON, not raw Codex CLI JSON, because the CLI itself exposes JSONL event streams via --json.
• Alias/function wrappers are supported only through shell-launch mode. If you pass an alias/function name without --codex-shell, the helper will treat it like a direct executable and it will likely fail.

Resources

• Stage guide (creation): references/creation.md
• Stage guide (invocation): references/invocation.md
• Stage guide (listing): references/listing.md
• Stage guide (deletion): references/deletion.md
• Helper script: scripts/invoke_persist.py (create-session, resolve, list-sessions, delete-session, delete-all-sessions, resume-json, resume-stream)