Thomashighbaugh/autoresearch-agent

autoresearch-agent

Spawn autoresearch as a headless OpenCode subprocess. The wrapper script scripts/autoresearch translates CLI subcommands into opencode --dangerously-skip-permissions -p "/autoresearch:<sub> <flags>".

Prerequisites

• opencode CLI in PATH (or set OPENCODE_BIN)
• The autoresearch skill installed in the target project or globally (~/.config/opencode/skills/autoresearch/)

Quick reference

# Foreground (blocks until done)
scripts/autoresearch ship --auto

# Background via agent-exec (preferred for long runs)
agent-exec run --timeout 3600000 -- scripts/autoresearch fix --guard "npm test"

Execution modes

1. Foreground — short tasks (<5 min)

Run directly when the result is needed immediately:

scripts/autoresearch ship --checklist-only
scripts/autoresearch plan "Reduce bundle size"

2. Background via agent-exec — long tasks (>5 min)

If agent-exec is available, prefer it for any run that may exceed 5 minutes. This keeps the calling agent responsive.

# Launch
agent-exec run \
  --cwd "$(pwd)" \
  --timeout 7200000 \
  -- scripts/autoresearch security --fail-on critical

# Check progress
agent-exec status <JOB_ID>
agent-exec tail --tail-lines 50 <JOB_ID>

# Wait for completion
agent-exec wait <JOB_ID>

Add --notify-file results.ndjson to get a completion event written when done.

3. Dry-run — verify command before launch

scripts/autoresearch -n ship --auto
# prints: + opencode --dangerously-skip-permissions -p '/autoresearch:ship --auto'

Workflow

1. Determine subcommand and flags from the user request
2. Check estimated duration — short (<5 min) → foreground; long → agent-exec
3. Verify prerequisites — which opencode, skill installed
4. Launch — foreground exec or agent-exec run
5. Monitor (background only) — agent-exec tail / status
6. Report results back to the user

Subcommands

See references/subcommands.md for the full subcommand table with flags.

| Subcommand | Typical duration | Recommended mode | |------------|-----------------|------------------| | ship --auto | 2-10 min | foreground | | ship --checklist-only | <1 min | foreground | | plan | 1-3 min | foreground | | security | 10-60 min | agent-exec | | debug | 10-60 min | agent-exec | | fix | 5-30 min | agent-exec | | scenario | 5-30 min | agent-exec | | predict | 3-10 min | foreground or agent-exec | | learn | 5-30 min | agent-exec | | (base loop) | unbounded | agent-exec with --timeout |

Environment variables

| Variable | Purpose | Default | |----------|---------|---------| | OPENCODE_BIN | Path to opencode binary | opencode | | OPENCODE_EXTRA_ARGS | Extra flags for opencode (e.g. --model sonnet) | (empty) | | AUTORESEARCH_DRY_RUN | Set 1 to print command without executing | 0 |

Error handling

• If opencode is not found, the script exits with a clear error message.
• If the autoresearch skill is not installed, OpenCode will report an unknown command. Fix: install the skill per the autoresearch README.
• If agent-exec is unavailable, fall back to direct foreground execution and warn the user that long runs will block.

Examples

# Ship a PR headlessly
scripts/autoresearch ship --auto

# Run 25 iterations of test coverage improvement in background
agent-exec run --timeout 3600000 \
  -- scripts/autoresearch "Goal: coverage to 90%" --iterations 25

# Security audit with CI gate
agent-exec run --timeout 7200000 \
  -- scripts/autoresearch security --fail-on critical --iterations 15

# Debug then fix pipeline
agent-exec run --timeout 1800000 \
  -- scripts/autoresearch debug --scope "src/**/*.ts" --iterations 10
# ... after completion:
agent-exec run --timeout 1800000 \
  -- scripts/autoresearch fix --from-debug --iterations 20