tomevault-io autoresearch-agent
Spawn autoresearch as a headless Claude Code subprocess. The wrapper script
scripts/autoresearch translates CLI subcommands into
claude --dangerously-skip-permissions -p "/autoresearch:<sub> <flags>".
Prerequisites
claudeCLI in PATH (or setCLAUDE_BIN)- The autoresearch skill installed in the target project or globally
(
~/.claude/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: + claude --dangerously-skip-permissions -p '/autoresearch:ship --auto'
Workflow
- Determine subcommand and flags from the user request
- Check estimated duration — short (<5 min) → foreground; long → agent-exec
- Verify prerequisites —
which claude, skill installed - Launch — foreground exec or
agent-exec run - Monitor (background only) —
agent-exec tail/status - 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 |
|---|---|---|
CLAUDE_BIN |
Path to claude binary | claude |
CLAUDE_EXTRA_ARGS |
Extra flags for claude (e.g. --model sonnet) |
(empty) |
AUTORESEARCH_DRY_RUN |
Set 1 to print command without executing |
0 |
Error handling
- If
claudeis not found, the script exits with a clear error message. - If the autoresearch skill is not installed, claude 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
Source: tumf/skills — distributed by TomeVault.