Awesome-openclaw-skills research-tracker

Manage autonomous AI research agents with SQLite-based state tracking. Use when spawning long-running research sub-agents, tracking multi-step investigations, coordinating agent handoffs, or monitoring background work. Triggers on: research projects, sub-agent coordination, autonomous investigation, progress tracking, agent oversight.

install

source · Clone the upstream repo

git clone https://github.com/sundial-org/awesome-openclaw-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/sundial-org/awesome-openclaw-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/research-tracker" ~/.claude/skills/sundial-org-awesome-openclaw-skills-research-tracker && rm -rf "$T"

OpenClaw · Install into ~/.openclaw/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/sundial-org/awesome-openclaw-skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/research-tracker" ~/.openclaw/skills/sundial-org-awesome-openclaw-skills-research-tracker && rm -rf "$T"

manifest: skills/research-tracker/SKILL.md

source content

Research Tracker

CLI tool for managing autonomous research agents with append-only state, instruction queues, and oversight.

Prerequisites

brew tap 1645labs/tap
brew install julians-research-tracker

Or:

go install github.com/1645labs/julians-research-tracker/cmd/research@latest

Quick Start

Start a research project

research init market-q1 --name "Q1 Market Analysis" --objective "Analyze competitor pricing and positioning"

As the research agent — log progress

export RESEARCH_SESSION_ID="$SESSION_KEY"  # Track which agent is writing

research log market-q1 STEP_BEGIN --step 1 --payload '{"task":"gather sources"}'
# ... do work ...
research log market-q1 STEP_COMPLETE --step 1
research heartbeat market-q1

Check status (from main session or heartbeat)

research status market-q1 --json
research context market-q1 --last 5  # Truncated context for prompts

Send instructions to running agent

research instruct market-q1 "Focus on enterprise segment" --priority URGENT
research stop-signal market-q1  # Request graceful stop

Agent checks for instructions

research pending market-q1 --json
research ack market-q1 --all  # Acknowledge after processing
research check-stop market-q1  # Exit 0 = stop, Exit 1 = continue

Commands Reference

Command	Purpose
`init <id> -o "..."`	Create project with objective
`list [--status active\|done\|all]`	List projects (includes `needs_attention` flag)
`show <id>`	Project details + recent events
`stop <id>`	Stop project, send STOP instruction
`archive <id>`	Archive completed project
`log <id> <event> [--step N]`	Log event (STEP_BEGIN, CHECKPOINT, BLOCKED, etc.)
`heartbeat <id>`	Update alive timestamp
`block <id> --reason "..."`	Mark blocked, needs input
`complete <id>`	Mark done
`status <id> [--json]`	Current state summary
`context <id> [--last N]`	Truncated context for agent prompts
`instruct <id> "text"`	Send instruction
`pending <id>`	List unacked instructions
`ack <id> [--all]`	Acknowledge instructions
`check-stop <id>`	Exit code: 0=stop, 1=continue
`audit <id> --verdict pass\|drift`	Log audit result

Event Types

STARTED

STEP_BEGIN

STEP_COMPLETE

CHECKPOINT

BLOCKED

UNBLOCKED

AUDIT_PASS

AUDIT_DRIFT

HEARTBEAT

DONE

STOPPED

TIMEOUT

Integration Pattern

Spawning a research agent

1. research init <project> --objective "..."
2. sessions_spawn with task including:
   - Project ID and objective
   - Instructions to use research CLI for state
   - Check stop signal before each step
   - Log progress with heartbeat
3. Heartbeat monitors: research list --json | check needs_attention
4. Send instructions via: research instruct <project> "..."

Agent loop (in spawned agent)

while research check-stop $PROJECT; [ $? -eq 1 ]; do
  research pending $PROJECT --json  # Check instructions
  research log $PROJECT STEP_BEGIN --step $STEP
  # ... do work ...
  research log $PROJECT STEP_COMPLETE --step $STEP
  research heartbeat $PROJECT
  STEP=$((STEP + 1))
done
research complete $PROJECT

Attention Detection

research list --json

includes

needs_attention: true

when:

Last event is BLOCKED
Has unacked URGENT or STOP instructions
Heartbeat stale (>5 min since last HEARTBEAT event)
Last audit was AUDIT_DRIFT

Database

SQLite at

~/.config/research-tracker/research.db

(WAL mode, append-only events).

Run

research db migrate

after install. Schema auto-migrates on first use.