ai-setup

Everything a coding-agent setup needs, in one repo you can install from: 50+ skills, Herdr plugins, and Pi packages. A guided installer walks you through the collection, sets up anything you're missing (like Pi or Herdr), and checks that it all works.

What's inside

Agent skills — 50+ skills for coding agents that read a skills/ tree (Claude Code included). They're about how you work with an agent, not what it builds: test-driven development, code review, refactoring, debugging, domain modeling, docs and diagrams, planning and backlog flow. Install one or all of them.

Herdr plugins — plugins for Herdr, a terminal multiplexer for coding agents. They ship as prebuilt, checksum-verified binaries, so you don't need Rust installed:

• reviewr - Work together with your AI to review code: read its diff, comment on lines, send the comments back with one key. It also reviews GitHub PRs and GitLab MRs (checks, threads, grouped replies) without leaving the pane.
• project-switcher — fuzzy project picker with a git-aware file tree and README preview.
• jumplist — jump back and forward through the panes you've focused, like editor navigation history.

Pi packages — extensions for the Pi coding agent.

• openai-fast — turn on OpenAI fast mode (the priority service tier) from inside Pi.
• herdr-worktree — continue the current session in a fresh Herdr-managed git worktree.
• mindwalk — run /mindwalk to replay the current session as light moving through a 3D map of the codebase.
• subagents — delegate tasks to subagents: chain them, run them in parallel, let them ask you questions mid-run.
• rewind — records file checkpoints as you work; branch to an earlier message and it restores your files to match.
• web-access — web_search and fetch_content tools for pages, PDFs, and GitHub repos.

The engineering flow

Most of the skills chain into one loop: you start with a vague idea and end with committed code. Each step feeds the next.

1. brainstorming — no idea yet. Talk through directions until one sticks; you end with a short brief.
2. wayfinder — the idea is real but fuzzy, or too big for one session. Break the unknowns into investigation tickets and work through them until the route is clear.
3. grill-with-docs — the agent interviews you, hard, until the idea is a spec. ADRs and a glossary fall out for free.
4. grill-with-examples — for hairy business logic: pin down every rule with concrete examples. Each example becomes a test later.
5. to-spec — turn the conversation into a spec on your tracker. No more questions, just writing it down.
6. to-tickets — split the spec into small tickets that each say what blocks them.
7. implement — build it. You approve a design sketch first, then it's TDD from there.
8. code-review — review the diff twice over: does it follow the repo's rules, and does it do what the spec said.
9. refactor — clean up, with the goal that the codebase ends up smaller than it started.
10. e2e-test — actually run the app and watch it work; a green test suite isn't proof. Add e2e-ux-test when a human has to like the UI too.
11. commit — tests green, then one clean Conventional Commits commit.

Two more sit off to the side. If something breaks mid-flow, diagnosing-bugs makes you find the actual cause before anyone touches a fix. And writing-clearly-and-concisely keeps the prose the loop produces (specs, commit messages, this README) readable.

You don't have to do all of it. A small, clear feature can start at step 7.

Guided setup

macOS and Linux

curl -fsSL https://raw.githubusercontent.com/Yassimba/ai-setup/main/install.sh | sh

Windows

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/Yassimba/ai-setup/main/install.ps1 | iex"

Then run:

ai-setup setup

A wizard walks through Pi packages, then Herdr plugins, then skills by category, and shows you the exact install plan before it runs anything. Pi packages and Herdr plugins go through their own package managers; skills are copied straight into your agents' skill trees. It ends by telling you what to try first.

Come back to it later:

ai-setup add       # choose more capabilities
ai-setup update    # update installed tooling and resources
ai-setup doctor    # check the setup
ai-setup add --skill tdd --herdr-plugin reviewr --yes

There's also an ai-setup skill, so a coding agent can run this same setup for you and ask before each step.

Install directly

You don't need the CLI — it just drives the tools below, and each one works on its own.

Agent skills

The CLI installs skills natively: it detects which coding agents you have (~/.claude, ~/.agents, ~/.codex, ~/.pi/agent) and copies the skills you pick — plus any skills they declare as dependencies — into each agent's skill tree.

ai-setup add --skill tdd --yes     # one skill (and whatever it depends on)
ai-setup update                    # refresh installed skills, backfill new agents

The repository is also on skills.sh:

npx skills add Yassimba/ai-setup

Claude Code users can get the same skills from its marketplace:

/plugin marketplace add Yassimba/ai-setup
/plugin install ai-setup@ai-setup

Pi packages

Each Pi package installs on its own:

pi install npm:@yassimba/pi-herdr-worktree
pi install npm:@yassimba/pi-mindwalk
pi install npm:@yassimba/pi-openai-fast
pi install npm:@yassimba/pi-rewind
pi install npm:@yassimba/pi-subagents
pi install npm:@yassimba/pi-web-access

See the package README under plugins/ for its commands and configuration.

Herdr plugins

Install any Herdr plugin straight from its folder in this repo:

herdr plugin install Yassimba/ai-setup/plugins/herdr-jumplist --yes
herdr plugin install Yassimba/ai-setup/plugins/herdr-project-switcher --yes
herdr plugin install Yassimba/ai-setup/plugins/herdr-reviewr --yes

Compiled plugins download checksum-verified binaries for macOS, Linux, or Windows from this repo's GitHub releases. No Rust needed.

Repository layout

• skills/<name>/SKILL.md — the reviewed shared skills. Category grouping lives in skills.sh.json.
• plugins/<name>/ — Pi packages and Herdr plugins, each installable on its own.
• cli/ai-setup/ — the Rust setup CLI.
• setup-catalog.json — the generated catalog the CLI embeds.
• .claude-plugin/ — exposes the shared skills through the Claude Code marketplace.
• drafts/ — unreviewed skills. Not published.
• personal/ — machine-specific skills. Never published.

Contributing

Install the JavaScript workspace and run the repository gates:

npm install
npm run check
npm run audit

Check the Rust CLI separately:

cargo fmt --manifest-path cli/ai-setup/Cargo.toml -- --check
cargo clippy --manifest-path cli/ai-setup/Cargo.toml --all-targets -- -D warnings
cargo test --manifest-path cli/ai-setup/Cargo.toml

If you change a reviewed skill or package catalog metadata, regenerate the embedded catalog:

npm run catalog:generate

For local Pi extension development, use scripts/sync-pi-extensions.sh status and scripts/sync-pi-extensions.sh link.

Credits

This repo builds on other people's work:

• Several of the coding skills are adapted from Matt Pocock's skills, and the research skill is his, copied verbatim.
• reviewr began as a fork of persiyanov/herdr-reviewr (MIT). It has diverged since — GitLab MRs, Windows builds, remote diff review — but the review pane at its heart is his design.
• subagents is a vendored fork of nicobailon/pi-subagents (MIT); web-access and rewind are reviewed distributions of his pi-web-access and pi-rewind-hook.
• mindwalk is vendored from cosmtrek/mindwalk (MIT), created by Ricko Yu. Pi session support began with ZacharyQin's upstream PR.
• ask-user and claude-bridge are reviewed distributions of edlsh/pi-ask-user and elidickinson/pi-claude-bridge.

Each package's README and THIRD_PARTY_NOTICES.md record the exact upstream version. Thanks, all.

License

MIT