davebcn87/pi-autoresearch/autoresearch-hooks

Claude Code and agent skill by davebcn87/pi-autoresearch

Trust tier 2
  • community
LLM review pending
Source check pending

Checking that the SKILL.md file is still in the repository.

Author pre/post-iteration hooks for an autoresearch session. Use when the user asks to add research fetching, Slack/webhook notifications, persistent learnings, auto-tagging, anti-thrash intervention, idea rotation, or any side effect around iterations.

Install

npx vskill@latest install davebcn87/pi-autoresearch/autoresearch-hooks

SKILL.md

The same SKILL.md was published earlier as davebcn87/pi-autoresearch/autoresearch-hooks.

autoresearch-hooks

Optional scripts that run at iteration boundaries in an autoresearch session. Two hooks, both transparent to the loop-running agent — their effect is a file on disk or a steer message.

.auto/hooks/
before.sh # fires before each iteration (prospective)
after.sh # fires after each log_experiment (retrospective)

Both files are optional. Files without the executable bit are silently ignored.


Contract

Stdin — before.sh

One JSON line. Parse with jq. Realistic example:

json
{
"event": "before",
"cwd": "/path/to/workdir",
"next_run": 6,
"last_run": {
"run": 5,
"status": "discard",
"metric": 42.1,
"description": "Simplified to sorted(arr) — copy cost dominates",
"asi": {
"hypothesis": "Built-in sort avoids Python overhead",
"next_focus": "list copy avoidance"
}
},
"session": {
"metric_name": "total_ms",
"metric_unit": "ms",
"direction": "lower",
"baseline_metric": 40.7,
"best_metric": 33.5,
"run_count": 5,
"goal": "optimize sort speed"
}
}
FieldNotes
last_runThe most recent run entry. null on a fresh session.
session.direction"lower" or "higher" — which end of the scale wins.
session.baseline_metricFirst run of the current segment. null until one run exists.
session.best_metricOptimal metric across kept runs only. null until one is kept.
session.goalThe session name set by init_experiment.
session.run_countTotal runs logged so far (any status).
Stdin — after.sh
json
{
"event": "after",
"cwd": "/path/to/workdir",
"run_entry": {
"run": 6,
"status": "discard",
"metric": 38.9,
"description": "Timsort hybrid slower on random",
"asi": {
"hypothesis": "Partial-sort heuristic on input distribution",
"learned": "Overhead dominates on random arrays"
}
},
"session": {
"metric_name": "total_ms",
"metric_unit": "ms",
"direction": "lower",
"baseline_metric": 40.7,
"best_metric": 33.5,
"run_count": 6,
"goal": "optimize sort speed"
}
}
FieldNotes
run_entryThe run just logged. Always present.
sessionSame shape as in before.sh, reflecting state after the run.
Output
  • Stdout (up to 8 KB) — delivered to the agent as a steer message on the next turn. Empty = silent.
  • Stderr + non-zero exit — surfaced as an error steer.
  • Timeout — 30 s hard kill; flagged in the observability entry.
Preservation

.auto/** survives the auto-revert — the entire .auto/ folder is preserved. (Legacy autoresearch.* paths are still preserved too, for in-flight sessions.)


Examples

Runnable reference scripts live in this skill's examples/ directory — one file per pattern. Paths are resolved against the skill directory (parent of SKILL.md). Browse them for inspiration; they're not policy.

  • examples/before/ — external search, qmd document search, anti-thrash, idea rotator, hypothesis reflection, context rotation
  • examples/after/ — learnings journal, macOS notification on new best, auto-tag winning commits

Each example is a complete, self-contained script with named constants, short helper functions, guard clauses, and intention-revealing names. Read the header comment for its purpose, copy to .auto/hooks/<stage>.sh, adapt.


Steps to add a hook

  1. Understand the session. Read .auto/prompt.md for the objective and metric; glance at .auto/measure.sh for the workload. Your hook should complement the loop, not duplicate it.
  1. Clarify the user's intent. What should happen, at which boundary? Research before / log after / notify on wins / intervene on thrash / etc.
  1. Start from an example in `examples/` that's closest to the intent (resolve against the skill directory). If nothing fits, write from scratch following the same style (named constants, short functions, guard clauses, JSON stdin parsed with jq). If the request combines retrospective + prospective concerns, use both before.sh and after.sh — don't overload one.
  1. Copy, adapt, mark executable.

``bash mkdir -p .auto/hooks cp "<skill-dir>/examples/before/external-search.sh" .auto/hooks/before.sh # ... adapt the script ... chmod +x .auto/hooks/before.sh ``

  1. Sanity-test with a piped mock before relying on it in the loop:

``bash jq -n ' { event: "before", cwd: ".", next_run: 1, last_run: null, session: { metric_name: "total_ms", metric_unit: "ms", direction: "lower", baseline_metric: null, best_metric: null, run_count: 0, goal: "test" } } ' | ./.auto/hooks/before.sh ``

For after.sh, swap last_run: null for a run_entry object (see the schema above).

  1. Commit the hook alongside other session files. It's preserved across reverts because it lives under .auto/.

Rules of thumb

  • Read whatever fields the agent naturally writes — asi.hypothesis, asi.next_focus, asi.learned, description. Don't invent a "hook input" field and instruct the agent to populate it; that breaks the transparency principle.
  • Silent is the default. Only print to stdout when you have something useful for the agent. Empty stdout means no steer.
  • Guard with early exits. [ -z "$query" ] && exit 0 is cheaper and clearer than wrapping everything in if.
  • One concern per script. If you want research + learnings, put them in separate files (before.sh and after.sh). Don't bundle.
  • No environment variables. Everything is on stdin; extract cwd (and anything else) with jq. There is no $AUTORESEARCH_WORK_DIR.

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewNot runA model review is scheduled for the next rescan.

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
8,094
Repository forks
460
Repository npm downloads, 7 days
815
7-day trend score
61

Stars and forks are for the whole GitHub repository, not this skill alone. Downloads are for the repository's npm package. Refreshed 17 May 2026, 6 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/davebcn87/pi-autoresearch/autoresearch-hooks/badge)](https://verified-skill.com/skills/davebcn87/pi-autoresearch/autoresearch-hooks)

Something wrong with this skill or its page? Tell us.