Opencode Keepalive

OpenCode plugin that keeps sessions alive: emits liveness heartbeats for external watchdogs and detects (and optionally recovers) stalled agents.

Getting Started

opencode-keepalive is a "watchdog" plugin for OpenCode. It monitors your agent's activity and helps ensure work doesn't grind to a halt without you knowing.

• Liveness Log: Emits continuous JSON telemetry to a background log file.
• Stall Detection: Automatically detects when an agent is "busy" but has stopped making progress.
• Auto-Recovery: Can automatically unstick stalled subagents by aborting them and nudging the parent agent to resume.

Installation

npm install opencode-keepalive

Enable it in your opencode.json (or opencode.jsonc):

{
  "plugins": [
    ["opencode-keepalive", {
      "childStallAction": "abort-resume-parent"
    }]
  ]
}

Quick Start

By default, the plugin works out of the box with zero configuration. It appends NDJSON (Newline Delimited JSON) heartbeats to:

~/.local/state/opencode-keepalive/heartbeat.ndjson
# or $XDG_STATE_HOME/opencode-keepalive/heartbeat.ndjson

You can view the pulse of your agent in real-time:

tail -f ~/.local/state/opencode-keepalive/heartbeat.ndjson | jq .

Common Recipes

1. Pipe to an external watchdog If you are using a process manager like Harbor that expects heartbeats on stdout:

["opencode-keepalive", { "output": "stdout" }]

2. Enable automatic subagent recovery To have the plugin automatically abort hung subagents and ask the parent to retry:

["opencode-keepalive", { "childStallAction": "abort-resume-parent" }]

3. Silence all output To keep the stall detection logic running but stop writing to any log:

["opencode-keepalive", { "output": "none" }]

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | intervalMs | number | 10000 | Interval between standard heartbeats (ms). | | includeDetails | boolean | true | Include event types, tool names, and stall details. | | includeSessionID | boolean | true | Include session IDs in heartbeats. | | stallMs | number | 120000 | Duration of no-progress before triggering a stall (ms). | | childStallAction | string | "report" | Action for stalled children: "report" or "abort-resume-parent". | | maxStallRecoveries | number | 3 | Max recovery attempts per child session. | | abortWaitMs | number | 30000 | Wait time after abort before nudging parent (ms). | | toolStallMsByTool | object | {...} | Per-tool stall budgets (e.g., {"glob": 60000}). | | bashQuickStallMs | number | 60000 | Stall budget for "quick" bash commands (ls, cat, etc.). | | resumeMessageTemplate| string | ... | Template used for parent nudge messages. | | output | string | "file" | Where to write: "file", "stdout", "stderr", or "none". | | logFile | string | ... | Custom path when output is "file". |

Troubleshooting

• No heartbeats appearing? Check the logFile path. If you are on a non-standard system, ensure XDG_STATE_HOME is set or provide an explicit logFile path.
• False positive stalls? If a long command (like a large git clone) is stalling, it might be classified incorrectly. You can unmap bash stall budgets by setting toolStallMsByTool: { "bash": null }.
• Too much log noise? Increase intervalMs to reduce the frequency of keepalive pulses.

How It Works

Event Model

The plugin emits envelopes with type: "heartbeat". The behavior is driven by 7 distinct triggers:

| Trigger | When it fires | |---------|---------------| | event | Any OpenCode event (except other heartbeats). | | idle | Periodic pulse when the system is completely idle. | | tool.execute.before | Immediately before a tool starts running. | | tool.execute.after | Immediately after a tool finishes. | | tool.running | Periodic "keepalive" pulse while a tool is in-flight. | | stall | Fired when the stall budget is exceeded. | | stall.recovery | Fired during an automatic recovery attempt (or error). |

Example Envelope:

{
  "type": "heartbeat",
  "properties": {
    "source": "opencode-keepalive",
    "timestamp": "2026-07-28T12:00:00.000Z",
    "unixMs": 1785240000000,
    "trigger": "stall",
    "sessionID": "sess_123",
    "parentID": "sess_000",
    "stalledForMs": 120000
  }
}

Emission Internals

1. Throttling: Standard events are batched. If an event occurs within intervalMs of the last heartbeat, it is held in a "pending" slot and flushed later. stall and stall.recovery triggers bypass this throttle for immediate visibility.
2. Keepalive Timer: While a tool is active, a dedicated timer re-emits the last tool.running signal at the intervalMs frequency. Crucially, these keepalives do NOT reset the stall clock.
3. Backpressure: When writing to stdout or stderr, the plugin respects stream drain signals to avoid memory bloat during heavy event volume.

Stall Detection Model

A session is considered stalled if its status is busy but no progress has been noted for the duration of its effective budget.

• Progress is: Message updates (part.updated, part.delta), tool lifecycle events (before, after), or command events.
• Progress is NOT: Internal heartbeats or tool.running keepalives.

Effective Budgets

The plugin uses a "strictest fuse" rule:

1. No tools in flight: Uses global stallMs.
2. Mapped tools in flight: If tools like glob or grep are running, the minimum of their mapped budgets is used (default 60s).
3. Unmapped tools only: If only unmapped tools (like a long npm install) are running, the short-fuse timer is disabled entirely to avoid false positives.

Bash Classification

The bash tool is special. The plugin inspects the first segment of the command to classify it:

• Quick: cat, ls, grep, jq, mkdir, rm, etc. These use bashQuickStallMs.
• Long: npm, docker, git, python, tsc, vitest, etc. These are unmapped by default.
• Unknown: Fail-safe to Long.

Subagent Recovery

When childStallAction is "abort-resume-parent":

1. stall.recovery is emitted.
2. The plugin calls session.abort(childID).
3. It waits for the child to become idle (up to abortWaitMs).
4. It sends a synthetic prompt to the parent session with the task_id of the stalled child, allowing the parent to naturally resume the work.

Architecture Tour

| Module | Responsibility | |--------|----------------| | index.ts | Entry point; wires options to state and hooks. | | hooks.ts | OpenCode lifecycle hooks; translates events to heartbeats/progress. | | heartbeat.ts | The core emission engine, throttler, and timers. | | sessions.ts | State tracking for active sessions and progress timestamps. | | tools.ts | Tool name normalization and effective budget calculation. | | bash-command.ts | Logic for classifying bash commands as quick vs long. | | recover.ts | Implementation of the abort-resume-parent sequence. | | state.ts | Runtime state and IO abstraction (the test seam). |

Edge Cases

• Unmapped Silence: If an agent is running an unmapped tool (like sleep 300) and the model is silent, the plugin will not stall. It relies on the external worker wall timeout.
• Waiting for User: When an agent is blocked on a permission.ask dialog, the stall timer is automatically disarmed to prevent "stalling" while waiting for you.

License

MIT