- name
- research-tracker
- description
- 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.
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-trackerOr: 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-q1Check status (from main session or heartbeat)
research status market-q1 --json
research context market-q1 --last 5 # Truncated context for promptsSend instructions to running agent
research instruct market-q1 "Focus on enterprise segment" --priority URGENT
research stop-signal market-q1 # Request graceful stopAgent 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 = continueCommands 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 $PROJECTAttention 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.