skills.rest
huangrt01
huangrt01COMMUNITY
Explore all skills by this author →
GitHub

codex-thread-heartbeat

Inspect and manage guarded launchd heartbeats for idle Codex control threads.

4.0k|479|Updated Apr 16, 2020
Search Tags:#Automation#CODEX#heartbeat#launchd#thread management#MacOS#idle detection
One-click install
npx skills add https://github.com/huangrt01/CS-Notes --skill codex-thread-heartbeat
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: codex-thread-heartbeat
Source: https://github.com/huangrt01/CS-Notes/tree/main/.codex/skills/codex-thread-heartbeat
Command: npx skills add https://github.com/huangrt01/CS-Notes --skill codex-thread-heartbeat

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Fixed-interval automation for Codex threads either interrupts active work or leaves dead time after tasks finish, and blindly running codex exec resume can race with the Codex App when a thread is still active. This Skill adds an idle guard that inspects local Codex thread state before sending any heartbeat prompt.

Core Features & Use Cases

  • Idle-guarded heartbeats: Reads ~/.codex/state_5.sqlite and the target rollout JSONL to check for recent final_answer, unresolved tool calls, and cooldown before sending via codex exec resume.
  • Launchd preset management: Install, enable, disable, kick, inspect, and uninstall named heartbeat presets (agent-harness, cs-notes, cs-notes-test) as macOS LaunchAgents.
  • Transport selection guidance: Prefers Codex App-native heartbeat automations for App-visible threads, with launchd + codex exec resume as a documented headless fallback.
  • Use Case: You run a long-lived CS-Notes controller thread and want it nudged every two hours to make one small verifiable improvement, but only when it has been idle for at least 120 seconds.

Quick Start

Ask the agent to install the cs-notes heartbeat preset and then report the launchd status, target thread, and idle-guard result.

Frequently Asked Questions about codex-thread-heartbeat

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I set up a periodic heartbeat for a Codex thread?▼

Run the bundled script with `install-preset <name>` to write and bootstrap a launchd plist for a known preset such as agent-harness or cs-notes. The heartbeat only sends when the target thread passes the idle guard.

How does the idle guard decide when to send a heartbeat?▼

The script parses the thread's rollout JSONL and refuses to send if there are function calls without outputs, a user message without a later final_answer, or no final_answer at all. It also enforces a minimum idle cooldown, defaulting to 120 seconds.

Will heartbeat messages appear in the Codex App UI?▼

The launchd plus codex exec resume transport is headless, so the open Codex App view may not refresh. For App-visible interaction, prefer the Codex App built-in heartbeat automation records under $CODEX_HOME/automations/.

How do I disable or uninstall a Codex thread heartbeat?▼

Use `heartbeat-disable <name>` to unload the launchd job while keeping the plist, or `heartbeat-uninstall <name>` to unload it and delete the plist file. `heartbeat-status <name>` shows the current loaded state.

What are the limitations of codex exec resume automation?▼

It is a headless fallback that can race with the App if used without idle checks, and the App renderer may not show the turn. It should be treated as best-effort and version-sensitive since it relies on local Codex state files.

Related Skills

Explore More Software Engineering Skills→
ma08ma08
28

rename-codex-thread

Rename Codex thread labels in the SQLite state database with timestamped backups.

Community
Intermediate
LudwigAJLudwigAJ

agent-autonomy-kit

Build a proactive task queue with heartbeat loops and status tracking.

Community
Intermediate
AesopScottAesopScott

stall-tuner

Calibrate heartbeat intervals and stall thresholds in the Health Monitor harness.

Community
Intermediate
omega-bredomega-bred
6

asc-wall-submit

Automate Wall of Apps entry submission and updates via App-Store-Connect-CLI.

Official
Intermediate