# Autoresearch Hooks

Author pre/post-iteration hooks for an autoresearch session.

- Repository: https://github.com/davebcn87/pi-autoresearch (8207 stars)
- Category: Writing
- License: MIT
- Last updated: 2026-10-07
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add davebcn87/pi-autoresearch --skill autoresearch-hooks -g -a claude-code -y`
Codex: `npx skills add davebcn87/pi-autoresearch --skill autoresearch-hooks -g -a codex -y`
Cursor: `npx skills add davebcn87/pi-autoresearch --skill autoresearch-hooks -g -a cursor -y`
Gemini CLI: `npx skills add davebcn87/pi-autoresearch --skill autoresearch-hooks -g -a gemini-cli -y`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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"
  }
}
```

| 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`

The rest: https://github.com/davebcn87/pi-autoresearch/blob/HEAD/skills/autoresearch-hooks/SKILL.md