| name | Codexy-OK |
| description | Use when planning sustained Codex work, durable threads, Goals, Automations, subagents, Skills, AGENTS.md context, or usage-aware Plus/Pro/unknown operating loops |
Codex Persistent Workflows
Overview
Treat Codex as a managed work loop: durable context, scoped execution, evidence, and review surfaces. The point is not maximum autonomy. The point is recoverable progress with clear stop conditions.
This skill synthesizes OpenAI's Codex workflow guidance, Jason Liu's Codex-maxxing workflow primitives, and current Codex usage-limit guidance. Jason's post is a practitioner workflow, not a product contract; exact plan limits and feature availability must be checked live.
Authority Boundary
Default to plan-only for persistent workflow actions unless the user explicitly authorizes execution. Do not create Goals, create/update Automations, pin/archive threads, spawn subagents, edit durable project files, or perform external side effects merely because the workflow would benefit from them.
Never infer missing authorization, subscription plan, budget, write scope, external action permission, or account-level limits. Mark them as Unknown and continue with conservative defaults. If authorization is missing, draft the proposed artifact or tool spec and ask for confirmation.
When to Use
Use this skill when a request involves:
- Persistent or recurring Codex work: pinned threads, heartbeats, automations, goals, long-running investigations.
- Scaling work: subagents, best-of-N, work queues, issue-style task decomposition, parallel exploration.
- Codex maximization: deciding which surface to use, how much context to preserve, how to make progress while away.
- Usage-aware planning: Plus/Pro/unknown plan assumptions, credits, local token history, or budget-sensitive workflows.
- Turning a proven workflow into a Skill, AGENTS.md rule, script, checklist, or durable artifact.
Do not use it for a tiny one-off task unless the user asks to preserve the workflow.
First Triage
Classify the request before acting:
| Type | Use | Avoid |
|---|
| One-off task | Direct local execution, short verification | Creating permanent threads or docs |
| Repeated workflow | Run once, then encode as Skill/script/checklist | Skill-writing before the process works |
| Ongoing workstream | Pinned thread plus external state file | Hiding all memory in chat history |
| Long-running objective | Goal with verifier and stop condition | Goal with only a vague ambition |
| Independent subtasks | Subagents with disjoint scopes | Parallel edits to shared files |
| Feedback loop | Heartbeat/automation with escalation rules | Unapproved sending, buying, deleting, merging |
Operating Contract
For substantial work, produce this contract. Infer only low-risk operational defaults; mark authorization, budget, plan, write scope, and external side-effect permissions as Unknown unless the user or an official source confirmed them:
Objective:
Scope:
Inputs:
External state file:
Tools/surfaces:
Subagents:
Verifier:
Artifacts:
Stop condition:
Escalation condition:
Plan/source confidence:
Authorization:
Write scope:
Budget:
External side effects:
Keep the contract short. The most important fields are scope, verifier, stop condition, and escalation condition.
Prompt Shape
Write Codex tasks like GitHub issues:
- Name the exact outcome and user-visible behavior.
- Include paths, components, reference modules, docs, and known constraints.
- State what must not change.
- Define the verification surface: tests, build, benchmark, screenshot, rendered document, CI, or manual review checklist.
- Tell Codex how to report: changed files, evidence, residual risk, blockers.
For large changes, start in ask/planning mode first, then execute against the accepted plan.
Sustained Workflow Build Order
- Inventory the current project: existing docs, state files, tests, scripts, open tasks, and user constraints.
- Draft the operating contract with explicit unknowns and authorization boundaries.
- Propose durable artifacts before creating them:
AGENTS.md, state file, task queue, verifier checklist, automation spec, and subagent plan.
- Execute only the authorized parts.
- Record evidence: commands run, exit status, cwd, artifacts produced, verification results, skipped checks, blockers, and next actions.
- End with a handoff that a fresh Codex session can resume without hidden chat context.
Durable Context
Use durable context only where the work will return value over time:
- Put project rules in
AGENTS.md, not repeated prompts.
- Put rolling state in
INIT.md, TODO.md, a project journal, or a plain-text vault.
- Store open loops, decisions, blockers, next actions, and verification commands outside chat.
- Use pinned threads for important workstreams, not every short task.
- Propose compaction or archival when long threads become expensive or stale; require explicit user confirmation before changing persistent thread state.
- Fork or side-thread when exploring alternatives that should not contaminate the main workstream.
The durable state should let a fresh Codex session answer: what is the goal, what has been decided, what remains open, and how is success checked?
Use separate durable files with non-overlapping roles:
AGENTS.md: stable project rules, build/test commands, coding standards, repository boundaries, and safety constraints.INIT.md or project state file: current objective, latest status, active decisions, open questions, next actions, and verification commands.TODO.md or issue list: decomposed tasks with owner, status, dependencies, and acceptance checks.
Do not duplicate the same state across files. Update the single source of truth before claiming the workflow is resumable.
Subagent Rules
Use subagents for independent work that can progress without shared state:
- Good: source extraction, independent design critique, code review, test triage by subsystem, alternative implementation sketches.
- Risky: multiple agents editing the same file, coupled architectural decisions, tasks where the main next step is blocked on the subagent result.
- Each subagent prompt needs scope, constraints, expected output, and whether file edits are allowed.
- The main agent owns integration, conflict checks, and final verification.
Before spawning subagents, define a subagent registry: name, scope, allowed files, edit permission, expected output, budget, and integration check. Save exact prompts and result links when future work depends on them; otherwise summarize subagent prompts and outputs in the main state file.
Do not treat subagent completion as proof. Require fresh evidence before declaring done.
Goals
Draft a Goal specification when the task must keep adapting over multiple steps and has an inspectable finish line. Create or activate a Goal only when the user explicitly asked for that persistent action.
Strong Goal ingredients:
- Outcome: what must be true.
- Verifier: test suite, benchmark, reproducible bug, rendered artifact, claim ledger, or review checklist.
- Constraints: APIs, public behavior, data boundaries, performance limits, approval boundaries.
- Artifact: PR, report, docs page, dashboard, figure, fixed test, or audit.
- Stop/escalate: when to mark complete, blocked, or ask the user.
Avoid Goals for "make this better" requests. Convert them into an exploration first, or write a verifier before starting.
If the runtime requires explicit user intent to create a Goal, do not call the Goal tool just because the task is long-running. Draft the objective, verifier, stop condition, blocked condition, and token/budget assumptions first.
Automations And Heartbeats
Recurring work must specify:
- Cadence.
- What to inspect.
- What counts as a trigger.
- What action is allowed.
- What must remain draft-only.
- When to notify or stop.
Default external actions to draft/recommend only. Sending, purchasing, deleting, merging, or replying externally requires explicit user authorization.
Never create, update, or delete an Automation unless the user explicitly asks for that persistent action. Otherwise, produce an automation draft with timezone, cadence, data sources, trigger condition, allowed action, draft-only boundary, notification path, expiration date, maximum run count, and failure/escalation behavior.
Review Surfaces
Prefer artifacts Codex and the user can inspect together:
- Static
index.html for lightweight dashboards or interactive reports.
- Side-panel browser for local UI review, Storybook, Slidev, Remotion, Streamlit, and other web surfaces.
- Rendered PDFs, slides, spreadsheets, and CSV tables for document work.
- Screenshots or pixel checks for visual claims.
If a durable artifact can replace a long prose summary, propose or create it depending on write authorization.
Plan-Aware Panels
Never guess the user's subscription. Use Plan: Unknown unless the user confirmed a plan in the current task or an official API/dashboard was checked.
| Panel | Guidance |
|---|
| Unknown | Conservative default. Use one main thread, minimal subagents, explicit verifiers, and avoid best-of-N unless it changes the decision quality. |
| Plus confirmed | Use durable threads and small parallel explorations. Keep long Goals narrow, externalize context aggressively, and check usage before heavy automations. |
| Pro confirmed | Consider broader parallelism, best-of-N, long Goals, and heartbeats for high-value workstreams. Still set budget, verifier, and human review boundaries. |
Do not hard-code quota, context-window, model, or price claims in this skill. Codex limits and credit rates are live product facts.
Local Usage Snapshot
Optional helper:
scripts/codex-usage-summary.sh --plan unknown
scripts/codex-usage-summary.sh --plan plus
scripts/codex-usage-summary.sh --plan pro
scripts/codex-usage-summary.sh --plan auto
The helper should follow a CodexBar-style probe pattern without depending on CodexBar: layered local providers, source labels, sanitized output, stale-source warnings, and graceful fallback when a surface is missing.
The helper may report local CLI version, login status, feature flags, whitelisted ~/.codex/config.toml settings, and aggregate local thread tokens_used from ~/.codex/state_5.sqlite.
It must not read third-party app caches, account email, auth tokens, cookies, or prompt contents. For account-level limits and credits, use the Codex Settings > Usage dashboard or an official admin/compliance API where available.
Common Mistakes
- Treating a long thread as memory. Real memory is external, inspectable, and editable.
- Starting a Goal without a verifier.
- Using automation as implicit permission for external side effects.
- Using subagents on coupled edits and then trusting their summaries.
- Writing exact Plus/Pro limit numbers that will drift.
- Letting usage planning override correctness, safety, or verification.
Completion Checklist
Before finishing a sustained Codex workflow:
- The task type and operating contract are clear.
- Persistent actions were either explicitly authorized or left as drafts.
- State that must survive the thread is written to a file.
- Subagents, if used, had independent scopes and were integrated.
- Verification evidence is fresh and named.
- Verification evidence includes command names, exit status, cwd, artifact paths, timestamps or freshness notes, key parameters, data/source versions or hashes when relevant, and known unverified areas.
- Budget/plan assumptions are labeled as unknown, user-confirmed, or officially checked.
- External actions stayed within the user's authorization.
- A fresh session can resume from the durable state file without relying on hidden chat history.
Source Anchors
- OpenAI, "How OpenAI uses Codex": code understanding, refactoring, performance, tests, development speed, focus, exploration, ask-mode-first, environment improvement, issue-style prompts, task queue,
AGENTS.md, best-of-N.
- Jason Liu, "Codex-maxxing": durable threads, external memory stores, computer-wide tools, heartbeats, Goals, side-panel artifact review, and verifier discipline.
- OpenAI Help Center and developer docs: Codex usage depends on plan and task complexity; current rate cards and credit behavior must be checked live.
