DeadlineDemon

Cross-CLI hook tool that sets session deadlines and nudges AI agents to finish on time.

Works with Codex CLI, Grok Build, and Claude Code.

Getting started

Codex plugin install

Install DeadlineDemon as a native Codex plugin from this GitHub repo:

codex plugin marketplace add bengHak/DeadlineDemon
codex plugin add deadline-demon@deadline-demon
codex

Open /hooks, review and trust the DeadlineDemon lifecycle hooks, and start a new thread.

The Codex plugin runs local Node.js hooks from the installed repo, so node must be available on the non-interactive shell PATH.

Grok, Claude, and local install

Install hooks with npx (no clone or global install required):

npx deadline-demon install

Hooks are copied to a persistent directory (~/.deadline-demon/) and wired into Grok, Codex legacy local plugins, and Claude Code. Re-run install after upgrading the package.

Enable the plugin or hooks in your harness (/plugins, /hooks in Codex/Grok; trust project hooks if using repo-local copies).

Set deadlines

One install provides both modes — pick per session when you set one:

| Mode | Behavior | |------|----------| | Nudge (default) | Countdown context each turn; tool calls are not blocked | | Hard | Same countdown; after time-up, non-wrap-up tool calls are blocked (git status/diff/add/commit still allowed) |

The number is minutes only from 1 to 1440 (no m, 분, or other unit suffix). Task text is shortened in hook output when it is very long.

Codex CLI examples

Codex reserves a leading / for its built-in slash command menu. Use the no-slash form so the prompt reaches DeadlineDemon's UserPromptSubmit hook:

deadline 8 "login page"
deadline 5 refactor auth
deadline-hard 10 "ship hotfix"

If you prefer the slash-shaped command in Codex, prefix it with a leading space:

 /deadline 8 "login page"
 /deadline-hard 10 "ship hotfix"

Claude Code examples

Use the slash form in Claude Code:

/deadline 8 "login page"
/deadline 5 refactor auth
/deadline-hard 10 "ship hotfix"

Commands

npx deadline-demon install [--dry-run]
npx deadline-demon uninstall [--dry-run]
npx deadline-demon doctor
npx deadline-demon status [--session-id <id>]
npx deadline-demon reset [--session-id <id>]

• uninstall — remove ~/.deadline-demon/, Grok/Codex plugin dirs, and the Claude hooks file created by install
• doctor — read-only checks for Node, hook manifests, persistent runtime, harness connections, and session state files
• status — show active sessions, remaining time, and mode (nudge or hard)
• reset — clear one session or all active sessions

doctor reports OK, INFO, WARN, and FAIL. Harnesses that are not installed are informational because each integration is optional. Broken or stale installed hooks are failures; run npx deadline-demon install again to repair them. The command exits with code 1 only when a FAIL is present and never changes files.

Grok note

If Grok ignores UserPromptSubmit stdout, nudge text may not appear. Tool blocking applies only to sessions set with /deadline-hard (the PreToolUse hook is installed but allows all tools for /deadline sessions).

Development

Build and install from source

git clone [email protected]:bengHak/DeadlineDemon.git
cd DeadlineDemon
npm install
npm run build
npx deadline-demon install

Install targets

| Harness | Path | |---------|------| | Codex native plugin | .codex-plugin/plugin.json → hooks/hooks.json → dist/cli.js | | Persistent package | ~/.deadline-demon/ | | Grok | ~/.grok/plugins/deadline-demon/ | | Codex | ~/.codex/plugins/deadline-demon/ | | Claude | ~/.claude/hooks/deadline-demon.json → ~/.deadline-demon/dist/cli.js |

Test

npm test

How it differs from timer hooks

Existing Claude timer hooks report elapsed time. DeadlineDemon reminds the agent of a deadline:

• /deadline N sets a nudge-only session timer
• /deadline-hard N sets the same timer with tool-call enforcement after time-up
• Every prompt injects remaining time with escalating urgency

License

MIT