opencode-research-tracker

OpenCode plugin that tracks research progress via JSONL state files and provides a research_log tool for agents to record structured research events.

Install

Add to opencode.json:

{
  "plugin": [
    "opencode-research-tracker"
  ]
}

Or install from npm:

npm install opencode-research-tracker

How It Works

The plugin does three things:

1. Provides a research_log tool that agents can call to record structured research events (approaches, hypotheses, experiments, metrics, decisions, etc.)
2. Automatically tracks session events — session start/end, status changes (busy/idle/error), active tool usage, and todo progress
3. Injects a system prompt instructing agents how to use the research_log tool effectively

All events are written as JSONL (one JSON object per line) to .opencode/research/<session-id>.jsonl in the project directory.

The research_log Tool

Agents call this tool at key research milestones. Supported event types:

| Event Type | Purpose | Key Fields | |---|---|---| | approach | Define a research direction/strategy branch | id, title, description, status, parent_id | | hypothesis | Record what you're testing and why | id, text, approach_id, status | | experiment_start | Record when launching an experiment | id, name, approach_id, hypothesis_id, params | | experiment_end | Record experiment results | experiment_id, status, summary, metrics | | metric | Record quantitative measurements | key, value, unit, approach_id | | decision | Record when choosing between alternatives | question, choice, alternatives, reasoning | | insight | Record important learnings | text, evidence | | direction | Record strategy pivots | from, to, reason, from_approach_id, to_approach_id | | blocker | Record blocking problems | id, title, description, severity | | blocker_resolved | Record how a blocker was fixed | blocker_id, fix, impact |

Approach Statuses

active | succeeded | failed | abandoned | paused

Experiment Statuses

success | failure | partial

Automatic Event Tracking

The plugin automatically records these events without agent action:

• session_start — when a session first becomes busy
• status — on every status transition (busy/idle/error), including active tool name and duration
• progress — when the todo list changes (captures all todos with completion count)

Output Format

Events are stored as JSONL at .opencode/research/<session-id>.jsonl. Each line is a JSON object with at minimum:

{"ts": "2025-01-15T10:30:00.000Z", "session_id": "ses_abc123", "source": "agent", "type": "approach", ...}

License

MIT