todo-enforcer

Todo continuation enforcer for pi-coding-agent — monitors todo state and injects prompts to keep agents working until all tasks complete.

Features

• Automatic task continuation — injects prompts when the agent goes idle with incomplete tasks
• Configurable rule engine — first-match-wins rule evaluation with built-in and custom conditions
• Multiple delivery modes — userMessage (default) or customMessage via pi's messaging API
• External command support — call external scripts/HTTP endpoints for dynamic continuation logic
• Spawn action — run pi -p in background to generate continuation guidance
• Stagnation detection — stops injecting when the agent is stuck on the same incomplete count
• Exponential backoff — rate-limits retries on LLM errors (429, rate limits, etc.)
• Message stall guard — prevents infinite loops from repeated identical messages
• Polling timer — re-evaluates after cooldown even without agent_end events
• Completion summary control — configurable completionSummary to suppress or enable the "all done" message (default: suppressed)

Installation

For Humans

npm install -g todo-enforcer

For AI Agents (pi / OpenCode / Claude Code / Codex)

Add to your settings.json:

{
  "packages": ["todo-enforcer"]
}

Or tell your agent:

Install and configure todo-enforcer by following:
https://raw.githubusercontent.com/buihongduc132/todo-enforcer/refs/heads/main/README.md

For pi (git-sourced)

In settings.json:

{
  "packages": ["https://github.com/buihongduc132/todo-enforcer"]
}

For pi (local path)

In settings.json:

{
  "packages": ["/path/to/todo-enforcer"]
}

Usage

todo-enforcer auto-activates via pi's agent_end lifecycle hook. No manual invocation needed.

How It Works

1. On each agent_end event, the enforcer reads the current todo state
2. It evaluates rules in order — the first matching rule wins
3. If a rule matches, it generates a prompt and delivers it to the agent
4. A polling timer re-checks after the cooldown expires

Default Rules

Rule	Condition	Action
incomplete-tasks-remain	Any pending/in_progress tasks	Inject continuation prompt
all-complete-celebration	All tasks completed	Inject summary (disabled by default)

Slash Commands

Command	Description
/enforcer-status	Show current enforcer state, rules, and injection count
/enforcer-switch <rule1,rule2,...>	Switch active rules for this session
/enforcer-switch reset	Reset to config defaults
/enforcer-reset	Reset all enforcer state for this session

Keyboard Shortcut

Shortcut	Action
Ctrl+Shift+T	Toggle enforcer enabled/disabled

Configuration

Create ~/.todo-enforcer.json (global) or .todo-enforcer.json (project-level):

{
  "enabled": true,
  "maxInjections": 5,          // Max injections per session
  "cooldownMs": 5000,          // Cooldown between injections (ms)
  "completionSummary": false,  // Suppress "all done" message (default)
  "detectStagnation": true,    // Stop injecting when stuck
  "stagnationThreshold": 3,    // Consecutive idle events before stagnation
  "backoff": {
    "enabled": true,
    "factor": 2,
    "maxDelayMs": 3600000,
    "errorPatterns": ["429", "rate limit", "No deployments available"]
  },
  "messageDelivery": {
    "mode": "userMessage",     // "userMessage" or "customMessage"
    "display": true,
    "triggerTurn": true
  },
  "rules": [
    {
      "name": "incomplete-tasks-remain",
      "condition": "has_incomplete",
      "action": "prompt",
      "prompt": "You have incomplete tasks. Continue working on them.\n\n[Status: {{completed_count}}/{{total_count}} completed, {{incomplete_count}} remaining]\n\nRemaining tasks:\n{{incomplete_list}}\n\nPick up where you left off."
    },
    {
      "name": "all-complete-celebration",
      "condition": "all_complete",
      "action": "prompt",
      "prompt": "All {{total_count}} tasks are complete. Great work.\n\nCompleted tasks:\n{{completed_list}}\n\nYou may now summarize the results or ask the user for next steps."
    }
  ]
}

Built-in Conditions

Condition	Description
has_incomplete	Any pending/in_progress tasks remain
all_complete	Every non-deleted task is completed
has_in_progress	At least one task is in_progress
none	Never matches (disabled rule)
always	Always matches

Template Variables

Variable	Description
{{incomplete_count}}	Number of incomplete tasks
{{completed_count}}	Number of completed tasks
{{total_count}}	Total non-deleted tasks
{{incomplete_list}}	Formatted list of incomplete tasks
{{completed_list}}	Formatted list of completed tasks
{{latest_user_message}}	Latest user message content
{{assistant_messages}}	Recent assistant messages

Actions

Action	Description
prompt	Inject a static template string
external	Call an external command or HTTP endpoint
spawn	Run pi -p in background with a template
noop	Do nothing (for logging/future use)

Architecture

todo-enforcer/
├── src/
│   ├── index.ts              ← Entry point — hooks, commands, shortcuts
│   ├── config.ts             ← Config loader + types + template interpolation
│   ├── conditions.ts         ← Built-in + custom condition evaluator
│   ├── external-caller.ts    ← External command/HTTP executor
│   ├── session-state.ts      ← Per-session state tracking
│   ├── todo-snapshot.ts      ← Reads todo state from session branch
│   ├── message-stall.ts      ← Repeated message + rate limit guard
│   ├── type-guards.ts        ← Runtime type guards
│   └── lib/
│       ├── plugin-logger.ts  ← File-based structured logger
│       ├── hooks-manager.ts  ← Hook registration and state
│       └── types.ts          ← Shared types
├── tests/                    ← Test suite (134 tests)
├── package.json
├── tsconfig.json
└── vitest.config.ts

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:ci

# Type check
npm run typecheck

License

MIT

Repository

GitHub: buihongduc132/todo-enforcer