Codex Same-Session Heartbeat
Objective
Determine whether Codex can support an autonomous heartbeat that returns the currently running agent to its task board every few minutes without starting a different agent, burning tokens while waiting, or relying on non-first-party automation as the core mechanism.
This brainstorm is deliberately narrower than the earlier Claude-oriented heartbeat plan in docs/plans/2026-07-08-001-feat-autonomous-heartbeat-headless-plan.md. That plan used a headless resumed CLI process on a schedule. The current question is stricter: can a running Codex session itself be woken or continued on a timer?
Source Corpus
The evidence base is the Last30Days research run named on the Trello card:
codex-goal-loop-wait-wake-heartbeat-same-session-scheduled-prompts-raw-brainstorm-v2.mdcodex-cli-first-party-scheduled-prompts-into-same-running-session-raw-v3.md
Those files are local Last30Days outputs, not part of this repository. The Trello card records their workstation paths and the instruction not to confuse the active private storage repo with the public example submodule.
Hard Constraints
- Prefer first-party Codex/OpenAI behavior.
- Preserve the same continuous live session, not merely the same serialized conversation context.
- Do not design a cron job whose only behavior is to wake a different agent.
- The heartbeat should pull the running agent back to the task board about every 10 minutes.
- Timers, loops, goals, or future scheduled prompts are acceptable only if they do not spin automatic continuations, burn tokens while waiting, or create runaway context growth.
- Distinguish session-context resume from true same-session steering.
- Distinguish ChatGPT/Codex scheduled tasks from prompt delivery into the currently running Codex CLI/TUI session.
Evidence Summary
The Last30Days corpus points to several adjacent capabilities, but not to a confirmed primitive that satisfies all constraints.
- Goal mode is relevant because goals are long-lived and can be paused/resumed, and the corpus says follow-up messages can steer long-running work. That is evidence for live-session steering, not evidence for time-based wake.
- Issue
openai/codex#28144asks for wait/wake support for goals without spending tokens. The request itself is evidence that durable wait/wake is a missing or at least not-yet-productized primitive. - Issue
openai/codex#28923reports goal-mode future-time waits spinning through many automatic continuations instead of sleeping. That is the exact failure mode this heartbeat design must avoid. - Issue
openai/codex#11415requestedcodex injectfor sending prompts into existing running sessions and was closed as not planned. That weakens the case for a first-party CLI affordance that can inject scheduled prompts into a live TUI session. - Issue
openai/codex#8317requested first-party CLI scheduling flags such as--at,--in, and--every. That frames CLI-native scheduling as requested behavior rather than confirmed current behavior. - The corpus cites first-party
codex exec resume/codex exec resume --lastas ways to continue non-interactive exec sessions with context. That is useful automation, but it is not necessarily the same continuous live session. - ChatGPT/Codex scheduled tasks and task-context automations appear relevant to scheduled work. The corpus does not prove that they inject into this live CLI session.
- Third-party or community tools that resume “same session” across agents are useful references, but they fail the first-party requirement.
Candidate Design Matrix
| Approach | First-party | Same continuous live session | No separate agent | No token-burn wait | Restart recovery | Immediate testability | Verdict |
|---|---|---|---|---|---|---|---|
| Goal-mode loop that asks Codex to wait until a future time | Yes | Yes, if kept in this session | Yes | No, evidence says it may spin | Poor unless paired with store | Yes | Reject as default; test only to measure current behavior |
| Long-running shell sleep inside current tool call, then return a heartbeat sentinel | Yes-ish, via local shell tool | Same turn/session, not a new agent | Yes | Likely no model-token burn during tool wait | Dies on restart | Yes | Useful experiment, but not a general prompt scheduler |
| Multiple pre-scheduled in-session timers if Codex exposes a timer primitive | Would be yes | Would be yes | Yes | Would be yes if real sleep | Weak unless timers persist | No known exposed primitive | Desired product shape, not current evidence |
codex exec resume --last from cron/system scheduler | Yes CLI, but external scheduler | No: resumes context in a new non-interactive process | No | Yes while idle | Good | Yes outside this live session | Practical fallback, fails strict same-session constraint |
| ChatGPT/Codex scheduled tasks or automations | First-party | Unproven for this CLI session | Likely separate scheduled task | Yes | Good | Not from this CLI alone | Useful adjacent product, not proof for this need |
| External injection into TUI via terminal, tmux, AppleScript, or bridge paste | No | Superficially yes | Maybe | Yes | Brittle | Maybe | Reject as core design; violates first-party and robustness |
| Persistent task store plus SessionStart restoration | First-party only if harness hook is first-party | No after restart; it restores a new session | No | Yes | Strong | Yes | Good mitigation, not a heartbeat |
| MCP/chained-prompt phase runner invoked manually | Depends on tool | Only when invoked | Yes | Yes | Strong for state, no automatic wake | Yes | Good workflow structure, not automatic wake |
Recommended Product Shape
The clean primitive is:
sleep_until/wake_atfor active goals: suspend the live session without spending tokens, then deliver a continuation prompt into the same running session when the timer or external event fires.
The primitive needs explicit semantics:
- A goal can enter a durable sleeping state with a wake time or wake condition.
- Sleeping does not generate model continuations.
- On wake, Codex receives a compact heartbeat prompt and the current goal state.
- The user can inspect, cancel, or reschedule the wake.
- If the process restarts, the wake either restores the same logical goal with a clear “resumed after restart” marker or reports that strict same-session wake was impossible.
- The UI/logs distinguish live-session wake, logical-session resume, and new scheduled task execution.
Immediate Experiment Plan
- Measure current goal-loop waiting behavior. Start a small goal that waits for a short future time, such as two minutes, and record whether Codex sleeps cheaply or spins automatic continuations. This directly validates the
#28923risk in the current environment. - Test shell-sleep wake inside this live session. Run a tool call such as
sleep 120; echo HEARTBEAT_READYand observe whether the harness returns control to the same agent turn without token-burning model work. This does not solve scheduled prompt injection, but it tests whether a non-token-burning wait can exist inside a live session. - Test context-resume fallback separately. Use
codex exec resume --lastonly as a labeled fallback experiment. The pass/fail question is not “does it work?” but “is the resulting process the same continuous live session?” The expected answer is no. - Record product gap. If goal waits spin and there is no timer primitive, open or update a product issue describing
sleep_until/wake_atfor goals and cite the observed measurements plus#28144,#28923,#11415, and#8317. - Use Agent Task OS as mitigation. Until first-party sleep/wake exists, keep task state durable on Trello and ensure session restoration reads the board, enforces one In Progress card, and keeps walking. This mitigates restarts and pauses, but should be labeled as restoration, not heartbeat.
Recommendation
Do not claim that Codex currently supports the requested heartbeat. The evidence supports a more precise statement:
Codex appears to have first-party pieces for long-running goals, scheduled work, and context resume, but the exact requirement - timed wake into this same continuous live session without token burn and without a separate agent - remains unproven and likely requires a product primitive.
The best next step is an evidence-gathering experiment pair: measure current goal-mode waiting, then measure shell-tool sleep behavior in the live session. If either passes, refine the design around the working primitive. If both fail or are too narrow, specify sleep_until / wake_at for active goals as the missing first-party capability.