davebcn87/pi-autoresearch/autoresearch-hooks
Claude Code and agent skill by davebcn87/pi-autoresearch
- community
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-hooksSKILL.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.
Both files are optional. Files without the executable bit are silently ignored.
Contract
Stdin — before.sh
One JSON line. Parse with jq. Realistic example:
| Field | Notes | |
|---|---|---|
last_run | The most recent run entry. null on a fresh session. | |
session.direction | "lower" or "higher" — which end of the scale wins. | |
session.baseline_metric | First run of the current segment. null until one run exists. | |
session.best_metric | Optimal metric across kept runs only. null until one is kept. | |
session.goal | The session name set by init_experiment. | |
session.run_count | Total runs logged so far (any status). |
Stdin — after.sh
| Field | Notes | |
|---|---|---|
run_entry | The run just logged. Always present. | |
session | Same 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 rotationexamples/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
- Understand the session. Read
.auto/prompt.mdfor the objective and metric; glance at.auto/measure.shfor the workload. Your hook should complement the loop, not duplicate it.
- Clarify the user's intent. What should happen, at which boundary? Research before / log after / notify on wins / intervene on thrash / etc.
- 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 bothbefore.shandafter.sh— don't overload one.
- 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 ``
- 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).
- 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 0is cheaper and clearer than wrapping everything inif.
- One concern per script. If you want research + learnings, put them in separate files (
before.shandafter.sh). Don't bundle.
- No environment variables. Everything is on stdin; extract
cwd(and anything else) withjq. 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
- SKILL.md in the repositoryCheckingskills/autoresearch-hooks/SKILL.md
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
[](https://verified-skill.com/skills/davebcn87/pi-autoresearch/autoresearch-hooks)