Heartbeat OpenCode Plugin

Heartbeat is a plugin stack for OpenCode with three modules:

• scheduler: human-managed cron jobs (including opencode run)
• task-manager: structured task state ([program][taskId])
• memory: shared append-only log + grep/search retrieval

The design model is:

• LLM = compute cycle
• Scheduler = clock/launcher
• Task manager + memory = state across cycles

Architecture

Components

1. Scheduler (/Users/pragneshbarik/Projects/heartbeat/scheduler/index.ts)

• Stores job definitions as JSON files.
• Runs jobs manually or on schedule (launchd on macOS).
• Streams all emitted stdout/stderr lines to one shared log file.

2. Task Manager (/Users/pragneshbarik/Projects/heartbeat/task-manager/index.ts)

• Stores tasks in a JSON file.
• Task key is [program][taskId].
• Supports parentTaskId for task hierarchies.
• Tracks status, priority, timestamps, and optional references.

3. Memory (/Users/pragneshbarik/Projects/heartbeat/memory/index.ts)

• Appends timestamped entries to one shared file.
• Supports:
  • tag lookup by [program]
  • exact lookup by [program][taskId]
  • regex grep across all entries
• Preserves multiline entries as a single memory record.

4. Unified Plugin Entry (/Users/pragneshbarik/Projects/heartbeat/index.ts)

• Merges tools from scheduler + task-manager + memory.
• Adds heartbeat_boot_context helper:
  • current task snapshot
  • recent task memory
  • queue slices (pending/running/blocked/raised)

Data Flow

1. Human creates a scheduler job.
2. Scheduler executes command or opencode run <prompt>.
3. Runtime output is streamed into the shared log.
4. Next cycle can query memory and task state, then continue.

Config Model

launchd label prefix is fixed in code:

• launchd label prefix: com.heartbeat.job

Bun executable resolution order:

• BUN_BIN env override
• bun from PATH
• fallback paths:
  • /opt/homebrew/bin/bun
  • /usr/local/bin/bun
  • ~/.bun/bin/bun

Configurable settings:

• logs directory/file
• jobs directory
• default job workdir
• task store file

Config precedence (lowest -> highest)

1. Built-in defaults (in code)
2. Global plugin config:
   • ~/.config/opencode/heartbeat.jsonc
3. Legacy fallback files:
   • heartbeat.config.json
   • .opencode/heartbeat.config.json
4. Workspace plugin config:
   • .opencode/heartbeat.jsonc
5. Environment override:
   • HEARTBEAT_CONFIG_PATH
   • legacy alias: HEARTBEAT_CONFIG

Setup

1. Install package in workspace

npm install heartbeat-opencode-plugin

2. Register plugin in OpenCode config

Create or edit opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["heartbeat-opencode-plugin"]
}

3. Add Heartbeat workspace config

Create .opencode/heartbeat.jsonc:

{
  "logs": {
    "dir": "./.heartbeat/logs",
    "file": "memory.log"
  },
  "scheduler": {
    "jobsDir": "./.heartbeat/jobs",
    "defaultWorkdir": "."
  },
  "taskManager": {
    "file": "./.heartbeat/tasks.json"
  }
}

Quick Start

1. Create a task:

• task_create(program, taskId, description, parentTaskId?, priority?, status?, references?)

2. Create a job:

• scheduler_create_opencode_job(...) or scheduler_create_command_job(...)

3. Test run once:

• scheduler_run_job(jobId)

4. Read memory:

• read_program_task(program, taskId?)
• read_program(program)
• memory_grep(pattern)

5. Mark done:

• task_mark_done(program, taskId)

Tool Surface

Scheduler tools:

• scheduler_create_opencode_job
• scheduler_create_command_job
• scheduler_list_jobs
• scheduler_get_job
• scheduler_update_job
• scheduler_run_job
• scheduler_install_job (macOS)
• scheduler_uninstall_job (macOS)
• scheduler_delete_job
• scheduler_info

Task tools:

• task_create
• task_list
• task_get
• task_update
• task_mark_done
• task_delete
• task_store_info

Memory tools:

• write_program_task
• read_program
• read_program_task
• memory_grep
• recent
• memory_info

Helper:

• heartbeat_boot_context

Local Development

bun install
bun run typecheck

Publish To npm

bun run typecheck
NPM_CONFIG_CACHE=/tmp/heartbeat-npm-cache npm pack --dry-run
npm login
npm publish --access public

Example Files

• /Users/pragneshbarik/Projects/heartbeat/examples/opencode.json
• /Users/pragneshbarik/Projects/heartbeat/examples/.opencode/heartbeat.jsonc
• /Users/pragneshbarik/Projects/heartbeat/examples/scheduler/jobs/daily-standup.json
• /Users/pragneshbarik/Projects/heartbeat/examples/scheduler/jobs/research-cycle.json
• /Users/pragneshbarik/Projects/heartbeat/examples/task-manager/tasks.json