New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Codex Thread Heartbeat

by huangruiteng in huangruiteng/CS-Notes

Inspect and manage guarded Codex App-native or launchd heartbeats for Codex main control threads.

MITAuto-check passed

Install Codex Thread Heartbeat

skills CLI
$ npx skills add huangruiteng/CS-Notes --skill codex-thread-heartbeat -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install huangruiteng/CS-Notes codex-thread-heartbeat --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/huangruiteng/CS-Notes.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.codex/skills/codex-thread-heartbeat .claude/skills/codex-thread-heartbeat && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
codex-thread-heartbeat
GitHub stars
4k
Token cost
~1.5k tokens
SKILL.md length
638 words
Files
3 (incl. scripts)
Skills in repo
39
Repo updated
First seen
Licence
MIT

At a glance

Inspect and manage guarded Codex App-native or launchd heartbeats for Codex main control threads.

  • Works in 3 steps: Codex App built-in heartbeat via App… → App-server control transport if a real… → Launchd + codex exec resume as a…
  • The user wants Codex to periodically continue a specific thread only when it is idle
  • SKILL.md covers Transport Choice, Quick Commands, Safety Rules and Open Source Positioning
  • Runs Python scripts from its folder; calls codex

What it does

Codex Thread Heartbeat is an agent skill from huangruiteng/CS-Notes. Inspect and manage guarded Codex App-native or launchd heartbeats for Codex main control threads. Use when the user wants Codex to periodically continue a specific thread only when it is idle, avoid interrupting active work, keep App-visible interactions, inspect thread status, or enable/disable project autopilot heartbeats.

Its SKILL.md is about 1.5k tokens, which your agent loads only when the skill is triggered. The skill folder holds 4 other files, including scripts (for example `agents/openai.yaml` and `scripts/codex-thread-queue.py`).

The licence is MIT.

When your agent uses it

  • The user wants Codex to periodically continue a specific thread only when it is idle
  • Avoid interrupting active work
  • Keep App-visible interactions
  • Inspect thread status

Example prompts

  • “/codex-thread-heartbeat”

Requirements

  • Python 3

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. Codex App built-in heartbeat via App automation records under $CODEX_HOME/automations/.
  2. App-server control transport if a real App server control socket is exposed.
  3. Launchd + codex exec resume as a headless fallback.

What it can do on your machine

Read from SKILL.md and the folder at commit f7b4e92. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • codex

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Codex Thread Heartbeat loads about 1.5k tokens when it runs. Until then it costs about 87 tokens; SKILL.md has 638 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~87
When it runs · the whole SKILL.md, loaded when a task matches
~1.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from huangruiteng/CS-Notes at commit f7b4e92, republished under its MIT licence (© huangruiteng). 638 words, ~1,474 tokens.

Download SKILL.mdSave it as .claude/skills/codex-thread-heartbeat/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
name
codex-thread-heartbeat
description
Inspect and manage guarded Codex App-native or launchd heartbeats for Codex main control threads. Use when the user wants Codex to periodically continue a specific thread only when it is idle, avoid interrupting active work, keep App-visible interactions, inspect thread status, or enable/disable project autopilot heartbeats.
metadata.short-description
Guarded Codex thread heartbeat automation

Codex Thread Heartbeat

Use this skill to set up or inspect local heartbeats that periodically nudge a specific Codex thread, but only after an idle guard passes.

The pain it solves:

  • Fixed short intervals keep the agent moving, but they can interrupt active work and waste tokens.
  • Fixed long intervals are cheaper, but create annoying dead time after a task finishes.
  • Codex App threads are persistent sessions, not ordinary CLI processes; blindly running codex exec resume can race with the App if the target thread is still active.

The bundled script reads Codex local thread metadata from ~/.codex/state_5.sqlite, checks the target rollout JSONL for recent final_answer, unresolved tool calls, and cooldown, then sends a heartbeat with codex exec resume <thread_id> only when it is safe. This is useful as a fallback, but App-native heartbeats are preferred when the user needs the interaction to show up in the Codex App UI.

Important limitation: codex exec resume is a headless fallback. It writes to the correct rollout and can complete the turn, but the currently open Codex App view may not refresh because the turn did not originate from that renderer. Do not leave long-running launchd heartbeats enabled if the user expects in-App visibility; prefer Codex App's built-in heartbeat automation or an App/server transport once a working control socket is available.

Transport Choice

Prefer this order:

  1. Codex App built-in heartbeat via App automation records under $CODEX_HOME/automations/.
    • Best for user-visible main-control threads.
    • The App bundle contains a heartbeat scheduler that checks renderer eligibility, collaboration mode, permissions, thread status, active flags, and recent rollout activity before turn/start.
    • It blocks on states such as waiting_on_user_input, waiting_on_approval, active_with_flags, and recent non-terminal rollout events, so it should not inject a heartbeat while the target thread is still running.
  2. App-server control transport if a real App server control socket is exposed.
    • Best theoretical shape: thread/resume then turn/start over the same notification stream the App can render.
    • Current local App process may only expose app-server over Electron-owned stdio, not a public control socket.
  3. Launchd + codex exec resume as a headless fallback.
    • Useful for log-based automation or CLI-only workflows.
    • Keep conservative idle guards and avoid expensive prompts because the App UI may not refresh.

Quick Commands

Show full SKILL.md (269 more words)Show less
App-Native Heartbeats

For user-visible controller threads, prefer the Codex App automation card or automation_update tool. Do not edit $CODEX_HOME/automations/*.toml directly unless you are only inspecting/debugging.

Known local App-native heartbeat records:

  • cs-notes-autopilot: CS-Notes controller thread, every 120 minutes.
  • agent-harness-heartbeat: Agent Harness controller thread.

Use App-native heartbeat when the user says they want:

  • messages visible in the Codex App thread;
  • no message injected while the thread is still running;
  • a target thread bound by target_thread_id;
  • normal App automation controls for pause/resume.
Headless Launchd Fallback

Run from any repo:

bash
~/.codex/skills/codex-thread-heartbeat/scripts/codex-thread-queue.py heartbeat-presets

Install built-in presets:

bash
~/.codex/skills/codex-thread-heartbeat/scripts/codex-thread-queue.py install-preset agent-harness
~/.codex/skills/codex-thread-heartbeat/scripts/codex-thread-queue.py install-preset cs-notes

Enable / disable:

bash
~/.codex/skills/codex-thread-heartbeat/scripts/codex-thread-queue.py heartbeat-disable agent-harness
~/.codex/skills/codex-thread-heartbeat/scripts/codex-thread-queue.py heartbeat-enable agent-harness

Inspect:

bash
~/.codex/skills/codex-thread-heartbeat/scripts/codex-thread-queue.py heartbeat-status agent-harness
~/.codex/skills/codex-thread-heartbeat/scripts/codex-thread-queue.py --title "agent-harness 主控" --cwd /path/to/repo status

One-off delivery test:

bash
~/.codex/skills/codex-thread-heartbeat/scripts/codex-thread-queue.py install-preset cs-notes-test

cs-notes-test runs every 30 seconds and disables itself after the first successful delivery.

Safety Rules

  • Prefer status or dry-run heartbeat before enabling an automation.
  • Do not use direct codex exec resume automation without idle checks.
  • Treat cli-resume heartbeats as headless. Confirm the user accepts log-based visibility, desktop notifications, or manual App reload before enabling them for expensive project work.
  • If the user needs Codex App-visible interaction, try the built-in heartbeat automation first and keep launchd disabled until the App-visible path is verified.
  • If the App exposes an app-server control socket in the future, prefer targeted turn/start; until then, codex exec resume is the practical fallback.
  • Keep heartbeat prompts bounded: ask for one small verifiable step, status-only behavior when work is running, and explicit changed files / validation.

Open Source Positioning

When packaging this skill publicly, describe it as a guarded local productivity automation for Codex power users, not as an official Codex API. Be explicit that it uses local Codex state files and conservative rollout inspection, so users should treat it as best-effort and version-sensitive.

© huangruiteng, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (scripts) in .codex/skills/codex-thread-heartbeat of huangruiteng/CS-Notes.

  • SKILL.md
  • agents/openai.yaml
  • scripts/codex-thread-queue.py

Open the folder on GitHubat commit f7b4e92

Compare with similar skills

Codex Thread Heartbeat next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Codex Thread Heartbeat compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Codex Thread Heartbeat this skillhuangruiteng/CS-Notes4k—~1.5kAutomated safety check: PassMIT
Safety Guardaffaan-m/ECC276k2 repos~554Automated safety check: NotesMIT
Node Inspect Debuggeropenclaw/openclaw392k1 repos~894Automated safety check: PassMIT
Guard Modegarrytan/gstack136k—~1kAutomated safety check: NotesMIT
Safety Guardaffaan-m/ECC276k—~323Automated safety check: NotesMIT
Safety Guardaffaan-m/ECC276k—~255Automated safety check: NotesMIT

Similar skills

  • Safety Guard

    affaan-m/ECC

    Guard against destructive operations with three modes: Careful intercepts dangerous commands (rm -rf, git push --force, DROP TABLE) for confirmation, Freeze locks writes to one directory, and Guard…

    276k GitHub starsUsed in 2 repos~554 tokens
    DevelopmentAuto-check: notes

  • Node Inspect Debugger

    openclaw/openclaw

    Debug Node.js with node inspect, --inspect, breakpoints, CDP, heap, and CPU profiles.

    392k GitHub starsUsed in 1 repo~894 tokens
    Frontend & DesignAuto-check passed

  • Guard Mode

    garrytan/gstack

    Switches on full safety by combining warnings before destructive commands with a block on edits outside one directory you choose, for work on production or live systems.

    136k GitHub stars~1k tokensUpdated today
    Agent WorkflowsAuto-check: notes

  • Safety Guard

    affaan-m/ECC

    本番システムでの作業時や、エージェントを自律的に実行する際に破壊的な操作を防ぐためにこのスキルを使用してください. An agent skill from affaan-m/ECC.

    276k GitHub stars~323 tokensUpdated 4 days ago
    Auto-check: notes

  • Safety Guard

    affaan-m/ECC

    使用此技能可防止在生产系统上工作或自主运行代理时进行破坏性操作。

    276k GitHub stars~255 tokensUpdated 4 days ago
    Auto-check: notes

  • Turn This Into A Thread

    sickn33/agentic-awesome-skills

    Turn a long idea, transcript, article or draft into a Twitter/X thread where every tweet stands alone.

    47k GitHub starsUsed in 1 repo~1.4k tokens
    Writing & ContentAuto-check passed

More from huangruiteng/CS-Notes

All 39 skills in this repo

  • CLI Creator

    huangruiteng/CS-Notes

    Build a composable CLI for Codex from API docs, an OpenAPI spec, existing curl examples, an SDK, a web app, an admin tool, or a local script.

    4k GitHub starsUsed in 2 repos~2.7k tokens
    Auto-check passed

  • Slack

    huangruiteng/CS-Notes

    A skill your agent uses when you need to control Slack from Clawdbot via the slack tool, including reacting to messages or pinning/unpinning items in Slack channels or DMs.

    4k GitHub starsUsed in 10 repos~578 tokens
    Auto-check passed

  • Codex Thread Reader

    huangruiteng/CS-Notes

    Locate and read a Codex thread by a codex thread link, thread id, or rollout path across all local CODEXHOME directories (~/.codex, ~/.codex-gpt, ...).

    4k GitHub stars~1.4k tokensUpdated yesterday
    Auto-check passed

  • Research Material Scout

    huangruiteng/CS-Notes

    A skill your agent uses when the user asks Codex to research, find learning materials, process "素材：" links, "请你读" / "精读" a material, build a material radar, or use SenSight-like broad information…

    4k GitHub stars~8.3k tokensUpdated yesterday
    Auto-check passed

  • GitHub

    huangruiteng/CS-Notes

    Interact with GitHub using the gh CLI. An agent skill from huangruiteng/CS-Notes.

    4k GitHub starsUsed in 27 repos~279 tokens
    Auto-check passed

  • AI Hotspots

    huangruiteng/CS-Notes

    Track and synthesize current AI hotspots into a bilingual HTML daily report.

    4k GitHub stars~1.2k tokensUpdated yesterday
    Auto-check passed

Questions about Codex Thread Heartbeat

What does Codex Thread Heartbeat do?

Inspect and manage guarded Codex App-native or launchd heartbeats for Codex main control threads. Codex Thread Heartbeat is an agent skill from huangruiteng/CS-Notes. Inspect and manage guarded Codex App-native or launchd heartbeats for Codex main control threads.

When should I use Codex Thread Heartbeat?

Codex Thread Heartbeat fits situations like: the user wants Codex to periodically continue a specific thread only when it is idle; avoid interrupting active work; keep App-visible interactions; inspect thread status.

How do I install Codex Thread Heartbeat in Claude Code?

Run `npx skills add huangruiteng/CS-Notes --skill codex-thread-heartbeat -a claude-code`. Or copy the skill folder (.codex/skills/codex-thread-heartbeat in huangruiteng/CS-Notes) into .claude/skills/codex-thread-heartbeat in your project. Claude Code loads it when a task matches its description.

How do I install Codex Thread Heartbeat in Codex?

Run `npx skills add huangruiteng/CS-Notes --skill codex-thread-heartbeat -a codex`. Or copy the skill folder (.codex/skills/codex-thread-heartbeat in huangruiteng/CS-Notes) into .agents/skills/codex-thread-heartbeat in your project. Codex loads it when a task matches its description.

Can I use Codex Thread Heartbeat in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add huangruiteng/CS-Notes --skill codex-thread-heartbeat -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/codex-thread-heartbeat, .gemini/skills/codex-thread-heartbeat, .github/skills/codex-thread-heartbeat and .opencode/skills/codex-thread-heartbeat in your project.

What does Codex Thread Heartbeat need to run?

Going by SKILL.md and its folder, Codex Thread Heartbeat needs Python for the scripts in its folder and the command-line tools its instructions call (codex). Our summary lists: Python 3.

Does Codex Thread Heartbeat access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Codex Thread Heartbeat safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Codex Thread Heartbeat use?

Codex Thread Heartbeat is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Codex Thread Heartbeat use?

About 1.5k tokens (SKILL.md is roughly 5.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Codex Thread Heartbeat?

Skills that share tags, products or a category with Codex Thread Heartbeat: Safety Guard (affaan-m/ECC, 276k stars), Node Inspect Debugger (openclaw/openclaw, 392k stars), Guard Mode (garrytan/gstack, 136k stars) and Safety Guard (affaan-m/ECC, 276k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Codex Thread Heartbeat?

huangruiteng (a GitHub user) maintains it in huangruiteng/CS-Notes, which has 4,000 GitHub stars. The repository holds 39 skills in this directory. The repository was last updated on October 8, 2026.

Source: huangruiteng/CS-Notes on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.