Research Tracker

Manage and track autonomous AI research projects with state logging, instruction queues, agent coordination, and progress monitoring via SQLite.

Security Scan

The skill's runtime instructions are coherent with a local research-tracking CLI, but metadata, install guidance, and installation sources raise concerns: it instructs tapping an unknown Homebrew tap and doing a go install from an external GitHub repo while declaring no required binaries or config paths.

Purpose & Capability

SKILL.md describes a local CLI (research) that manages SQLite state for coordinating autonomous agents — this matches the skill name/purpose. However, the registry metadata lists no required binaries or config paths while the instructions clearly require installing a 'research' binary and will use ~/.config/research-tracker/research.db. That metadata/instruction mismatch should be clarified.

Instruction Scope

Instructions are narrowly scoped to installing/running the 'research' CLI, logging events, heartbeats, checking for instructions, and using a local SQLite DB. The SKILL.md does not instruct the agent to read arbitrary unrelated files or to exfiltrate data. It does reference exporting RESEARCH_SESSION_ID (and implies SESSION_KEY) which could be sensitive, so care is needed when setting session environment variables.

Install Mechanism

There is no formal install spec in the registry, but the SKILL.md tells users/agents to 'brew tap 1645labs/tap' and 'brew install julians-research-tracker' or 'go install github.com/1645labs/julians-research-tracker/cmd/research@latest'. Both commands fetch and install code from third-party sources (unknown tap/org). Homebrew taps and go installs can execute arbitrary code; this is the highest-risk area and should be audited or replaced with verified release artifacts/checksums.

Credentials

The skill declares no required environment variables, but the docs reference RESEARCH_SESSION_ID (and SESSION_KEY) for tracking agent sessions. The local DB path (~/.config/research-tracker/research.db) is also used. Requested environment access is minimal and consistent with purpose, but the mismatch between declared and referenced env vars should be fixed and SESSION_KEY may be sensitive—avoid exporting secrets without review.

Persistence & Privilege

The skill does not request elevated privileges or an 'always' presence. It will create and persist a local SQLite DB in the user's home config directory and run migrations; that persistent local state is expected for this tool but you should be aware it will store events and state on disk.

What to consider before installing

This skill appears to be a wrapper around a local CLI that tracks agent work in a SQLite DB — functionally coherent. However: (1) the SKILL.md tells you to add an unknown Homebrew tap and to go install code from github.com/1645labs — review that repository and the brew tap contents before installing; these sources can run arbitrary code. (2) The registry metadata omits required binaries/env/config that the instructions use (research binary, RESEARCH_SESSION_ID, and ~/.config/research-tracker/research.db) — ask the publisher to fix metadata. (3) Treat SESSION_KEY and RESEARCH_SESSION_ID as potentially sensitive; avoid exporting secrets into long-lived environment variables unless you understand what they contain. (4) Prefer installing from a verified release (checksums, signed releases), run initial installs in an isolated environment (VM/container), and inspect the code/migration scripts before running migrations. If you cannot audit the tap/repo, consider this a risk and do not install on a sensitive machine.

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.