Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/release-prepare.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ jobs:
GH_TOKEN: ${{ github.token }}
run: |
[[ "$SOURCE" =~ ^[a-f0-9]{40}$ ]]
[[ "$SOURCE" == "$(gh api repos/GaganSD/pi-extensions/commits/main --jq .sha)" ]]
[[ "$SOURCE" == "$(gh api repos/GaganSD/coding-agent-toolkit/commits/main --jq .sha)" ]]
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ inputs.source_sha }}
Expand Down
2 changes: 1 addition & 1 deletion .gitleaks.toml
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
title = "pi-extensions secrets"
title = "coding-agent-toolkit secrets"
[extend]
useDefault = true
80 changes: 53 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,31 +18,34 @@

</td></tr></table>

<p align="center"><strong>Coding Agent Tools For Herdr and <a href="https://pi.dev">Pi</a></strong></p>
<p align="center"><strong>Extensions for <a href="https://pi.dev">Pi</a> · Mods for <a href="https://herdr.dev">Herdr</a></strong></p>

<p align="center">
<a href="https://github.com/GaganSD/pi-extensions/actions/workflows/publish.yml"><img src="https://img.shields.io/github/actions/workflow/status/GaganSD/pi-extensions/publish.yml?branch=main&style=flat-square&label=CI&color=10b981&labelColor=18181b" alt="CI Status" /></a>
<a href="https://github.com/GaganSD/pi-extensions/actions/workflows/quickstart.yml"><img src="https://img.shields.io/github/actions/workflow/status/GaganSD/pi-extensions/quickstart.yml?branch=main&style=flat-square&label=Quickstart&color=10b981&labelColor=18181b" alt="Quickstart CI Status" /></a>
<a href="https://github.com/GaganSD/coding-agent-toolkit/actions/workflows/publish.yml"><img src="https://img.shields.io/github/actions/workflow/status/GaganSD/coding-agent-toolkit/publish.yml?branch=main&style=flat-square&label=CI&color=10b981&labelColor=18181b" alt="CI Status" /></a>
<a href="https://github.com/GaganSD/coding-agent-toolkit/actions/workflows/quickstart.yml"><img src="https://img.shields.io/github/actions/workflow/status/GaganSD/coding-agent-toolkit/quickstart.yml?branch=main&style=flat-square&label=Quickstart&color=10b981&labelColor=18181b" alt="Quickstart CI Status" /></a>
<a href="https://snyk.io"><img src="https://img.shields.io/badge/security-snyk%20monitored-10b981?style=flat-square&labelColor=18181b&logo=snyk&logoColor=white" alt="Security: Snyk" /></a>
<a href="https://github.com/GaganSD/pi-extensions/actions"><img src="https://img.shields.io/badge/vulnerabilities-0%20reported-10b981?style=flat-square&labelColor=18181b" alt="Vulnerabilities: 0" /></a>
<a href="https://github.com/GaganSD/coding-agent-toolkit/actions"><img src="https://img.shields.io/badge/vulnerabilities-0%20reported-10b981?style=flat-square&labelColor=18181b" alt="Vulnerabilities: 0" /></a>
<br />
<a href="https://pi.dev"><img src="https://img.shields.io/badge/pi-%3E%3D1.0.0-27272a?style=flat-square&labelColor=18181b" alt="Pi >= 1.0.0" /></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-27272a?style=flat-square&labelColor=18181b" alt="License: MIT" /></a>
</p>

---

A monorepo of modular extensions engineered specifically for the Pi coding agent. Each package adheres to strict context-efficiency principles, zero-bloat architecture, and native Pi integration. Detailed subagent delegation benchmarks live in [`benchmarks/README.md`](./benchmarks/README.md).
A monorepo of **Pi coding-agent extensions** and **Herdr mods**. Each integrates natively with its host, with minimal overhead and focused functionality. Pi extensions and Herdr mods are installed separately.

- [Pi extensions](#pi-extensions): terminal UI, subagent delegation, web search, interactive interviews, and permission controls.
- [Herdr mods](#herdr-mods): a local-first token-usage dashboard for Pi, Codex, Claude Code, and OpenCode sessions.

## Design Principles

- **Minimal by Design** — Engineered for zero-context bloat and preserve the agent's context window. Prompts and schemas stay minimal while benchmaxxing every tool for effectiveness.
- **Keyless by Default** — Essential utilities like public web and code retrieval work instantly out of the box.
- **Pi-Native** — Built strictly around Pi's extension lifecycle, tools, custom slash commands, themes, and configuration store.
- **Minimal by Design** — Focused tools with minimal overhead. Pi prompts and schemas stay small to preserve the agent's context window.
- **Keyless by Default** — Public web and code retrieval work without API keys; Insights reads local session data without an account.
- **Native Integration** — Pi extensions use Pi's extension lifecycle, tools, slash commands, and themes. Herdr mods use Herdr's native mod system.

---

## Packages
## Pi extensions

| Package | Description | Install |
| :--- | :--- | :--- |
Expand All @@ -52,30 +55,21 @@ A monorepo of modular extensions engineered specifically for the Pi coding agent
| [pi-ask](./pi-ask/) | Structured interactive TUI interviews for human-in-the-loop decisions. | `pi install npm:@gagansd/pi-ask` |
| [pi-automode](./pi-automode/) (beta) | Permission gate for Pi: risky calls stop for a local decision, protected paths block, exact rules cut repeated asks. | `pi install npm:@gagansd/pi-automode` |

---

## Herdr mods
### Install Pi extensions

[Insights](./herdr-insights/) is a native token-usage dashboard for
[Herdr](https://herdr.dev), with model rankings, usage trends, and an activity
heatmap. It reads local Pi, Codex, Claude Code, and OpenCode sessions. Install it
separately from the Pi extensions; see its [README](./herdr-insights/README.md).
#### All-in-one (local checkout)

## Installation

### All-in-One Suite (Monorepo)

Point Pi to a clone of this repository to register all 5 extensions, skills, and Slate themes simultaneously:
Requires Node.js `>=22.19.0` and Pi `>=1.0.0`. Point Pi to a clone of this repository to register all five Pi extensions, skills, and Slate themes. This does **not** install Herdr mods:

```bash
git clone https://github.com/GaganSD/pi-extensions.git
cd pi-extensions
git clone https://github.com/GaganSD/coding-agent-toolkit.git
cd coding-agent-toolkit
pi install .
```

Then reload Pi with `/reload`.

### Standalone (NPM)
#### Individual extensions (npm)

Install individual extensions directly:

Expand All @@ -89,8 +83,30 @@ pi install npm:@gagansd/pi-automode # Permission gate (opt-in, off by default)

---

## Herdr mods

| Mod | Description | Install |
| :--- | :--- | :--- |
| [Insights](./herdr-insights/) | Local-first token-usage dashboard with model rankings, usage trends, and an activity heatmap. Reads Pi, Codex, Claude Code, and OpenCode sessions. | From a checkout: `npm run install:local --prefix herdr-insights -- --open` |

### Install Insights

Requires [Herdr](https://herdr.dev) and **Node.js 22.15+**. No dependencies or account needed. From this repository's root:

```bash
npm run install:local --prefix herdr-insights -- --open
```

The installer validates the mod with `herdr-app check` and opens an **Insights** tab. It installs only `mods/insights/` under `~/.config/herdr-app`, leaving layouts, keys, and terminals unchanged. No Pi extension installation is required.

See the [Insights README](./herdr-insights/README.md) for standalone checkout instructions, settings, privacy details, and uninstallation, or [RECIPE.md](./herdr-insights/RECIPE.md) for the mod specification.

---

## Development & Building

### Pi extensions

**Prerequisites**: Node.js `>=22.19.0`, npm `>=10.0.0`, Pi `>=1.0.0`.

```bash
Expand All @@ -104,7 +120,16 @@ npm run build --prefix pi-slate # or pi-subagents, pi-web-search, pi-ask,

After `pi install .`, local edits apply on `/reload`.

### Token counter
### Herdr mods

Insights uses Node.js `22.15+`; its native validation requires Herdr. Run its checks separately from the root Pi extension suite:

```bash
npm test --prefix herdr-insights
npm run check --prefix herdr-insights
```

### Shared token counter

After installing root development dependencies, count literal text locally (no API calls):

Expand All @@ -127,7 +152,7 @@ individual extensions.

---

## Benchmarks & Performance
## Pi Subagent Benchmarks & Performance

`@gagansd/pi-subagents` is continuously benchmarked against standard delegation alternatives on dynamic multi-step workflows (parallel join, bounded repair, conditional fanout):

Expand All @@ -145,12 +170,13 @@ See [`benchmarks/README.md`](./benchmarks/README.md) for full benchmark methodol
## Repository Structure

```text
pi-extensions/
coding-agent-toolkit/
├── pi-slate/ # Minimal TUI, custom surfaces, diff viewers & themes
├── pi-subagents/ # High-efficiency subagent delegation harness
├── pi-web-search/ # Multi-provider web & code search with classifier
├── pi-ask/ # Structured TUI interview & clarification modal
├── pi-automode/ # Parent-session permission gate with verified launcher
├── herdr-insights/ # Native Herdr mod: local coding-agent token-usage dashboard
├── benchmarks/ # Multi-model workflow benchmarking suite
├── docs/ # Architecture, CI/CD, and release guides
└── scripts/ # Build, test, security scanning, and release tools
Expand Down
9 changes: 8 additions & 1 deletion docs/ci-cd.md
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ Complete these steps before the first release:
`@gagansd/pi-subagents`, `@gagansd/pi-web-search`, and
`@gagansd/pi-automode`, configure:
- GitHub owner: `GaganSD`
- Repository: `pi-extensions`
- Repository: `coding-agent-toolkit`
- Workflow filename: `publish.yml` (not the full path)
- Environment: `npm`
- Allow direct `npm publish`
Expand All @@ -189,6 +189,13 @@ Complete these steps before the first release:
They protect supported credential formats before GitHub accepts a push;
the Actions scanner is not a replacement.

### Repository rename follow-up

After a GitHub repository rename, update each npm package's trusted publisher to
`GaganSD/coding-agent-toolkit` before publishing. GitHub URL redirects do not
update npm's external trust configuration. Also verify the release GitHub App's
repository access and any external Snyk integration after the rename.

## Snyk dependency scan

Snyk runs inside the `Package / <name>` matrix job in `ci.yml`, after the
Expand Down
6 changes: 3 additions & 3 deletions herdr-insights/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,13 @@ Requires Herdr and **Node.js 22.15+**. No dependencies or account needed.

Ask your agent:

> Read https://github.com/GaganSD/pi-extensions/tree/main/herdr-insights and install the Insights mod following its RECIPE.md and my Herdr AGENTS.md.
> Read https://github.com/GaganSD/coding-agent-toolkit/tree/main/herdr-insights and install the Insights mod following its RECIPE.md and my Herdr AGENTS.md.

Or install from a checkout:

```sh
git clone https://github.com/GaganSD/pi-extensions.git
cd pi-extensions
git clone https://github.com/GaganSD/coding-agent-toolkit.git
cd coding-agent-toolkit
npm run install:local --prefix herdr-insights -- --open
```

Expand Down
18 changes: 13 additions & 5 deletions llms.txt
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
# Pi extensions
# Coding Agent Toolkit

> Extensions for the Pi coding agent: Slate (terminal UI), Ask (structured interviews), Automode (permission gate), Subagents (delegation), and Web Search (cited public retrieval).
> Extensions for the Pi coding agent and native mods for Herdr. Pi extensions include Slate (terminal UI), Ask (structured interviews), Automode (permission gate), Subagents (delegation), and Web Search (cited public retrieval). The Insights mod provides a local-first Herdr token-usage dashboard for Pi, Codex, Claude Code, and OpenCode sessions.

Packages live at the repository root, not under `packages/`. Install each package separately. All five are published on npm.
Packages and mods live at the repository root, not under `packages/`. Pi extensions and Herdr mods are installed separately. All five Pi extensions are published on npm; install them individually with `pi install npm:<package>` or together with `pi install .` from a checkout. Neither method installs Herdr mods.

## Documentation

- [Root README](README.md): package index, install, development
- [Root README](README.md): separate Pi extension and Herdr mod indexes, installation, development
- [Slate README](pi-slate/README.md): TUI setup, commands, themes, composer keys
- [Ask README](pi-ask/README.md): `ask_user` contract, commands, TUI-only behavior
- [Automode README](pi-automode/README.md): permission gate, commands, rules, verified launcher, classifier review
- [Subagents README](pi-subagents/README.md): delegation contract and benchmarks
- [Web Search README](pi-web-search/README.md): tools, native Parallel MCP, optional Pi-hosted Jev classifier, config, credentials, limits
- [Web Search research](pi-web-search/docs/research.md): opt-in multi_search and Jev

## Packages
## Pi extensions

- [Root manifest](package.json): collection extensions, skills, and themes
- [Slate package](pi-slate/package.json): `npm:pi-slate`
Expand All @@ -23,6 +23,14 @@ Packages live at the repository root, not under `packages/`. Install each packag
- [Subagents package](pi-subagents/package.json): `npm:@gagansd/pi-subagents`
- [Web Search package](pi-web-search/package.json): `npm:@gagansd/pi-web-search`

## Herdr mods

- [Insights README](herdr-insights/README.md): installation, settings, privacy, development, uninstallation
- [Insights recipe](herdr-insights/RECIPE.md): native mod specification, architecture, rebuild requirements
- [Insights manifest](herdr-insights/package.json): local install, uninstall, test, and check scripts; not published on npm

Insights requires Herdr and Node.js 22.15+. From a checkout, run `npm run install:local --prefix herdr-insights -- --open`. The installer validates and opens the mod without changing layouts, keys, or terminals. Session data stays local; no account or API key is required. Run Insights tests separately with `npm test --prefix herdr-insights` and native checks with `npm run check --prefix herdr-insights`.

## Agent indexes

- [Web Search llms.txt](pi-web-search/llms.txt): search navigation and source contracts
Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 3 additions & 3 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
{
"name": "pi-extensions",
"name": "coding-agent-toolkit",
"private": true,
"description": "Monorepo of Pi extensions I use and build, including keyless public web/code search through native Pi MCP.",
"description": "Pi coding-agent extensions and native Herdr mods, including keyless web/code search and local token-usage insights.",
"license": "MIT",
"author": "Gagan Devagiri",
"repository": {
"type": "git",
"url": "git+https://github.com/GaganSD/pi-extensions.git"
"url": "git+https://github.com/GaganSD/coding-agent-toolkit.git"
},
"scripts": {
"test": "npm test --prefix pi-slate && npm test --prefix pi-ask && npm test --prefix pi-web-search && npm test --prefix pi-subagents && npm test --prefix pi-automode",
Expand Down
6 changes: 3 additions & 3 deletions pi-ask/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ Gives your agent a way to interview you in a structured form — brainstorming,

One skill (~20-token description), built for context minimisation.

![Multi-select](https://raw.githubusercontent.com/GaganSD/pi-extensions/main/pi-ask/assets/multi.png)
![Multi-select](https://raw.githubusercontent.com/GaganSD/coding-agent-toolkit/main/pi-ask/assets/multi.png)

![Single-select](https://raw.githubusercontent.com/GaganSD/pi-extensions/main/pi-ask/assets/single.png)
![Single-select](https://raw.githubusercontent.com/GaganSD/coding-agent-toolkit/main/pi-ask/assets/single.png)

![Text](https://raw.githubusercontent.com/GaganSD/pi-extensions/main/pi-ask/assets/text.png)
![Text](https://raw.githubusercontent.com/GaganSD/coding-agent-toolkit/main/pi-ask/assets/text.png)

## Install

Expand Down
4 changes: 2 additions & 2 deletions pi-ask/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,10 @@
"terminal-ui",
"tui"
],
"homepage": "https://github.com/GaganSD/pi-extensions/tree/main/pi-ask",
"homepage": "https://github.com/GaganSD/coding-agent-toolkit/tree/main/pi-ask",
"repository": {
"type": "git",
"url": "git+https://github.com/GaganSD/pi-extensions.git",
"url": "git+https://github.com/GaganSD/coding-agent-toolkit.git",
"directory": "pi-ask"
},
"files": [
Expand Down
2 changes: 1 addition & 1 deletion pi-automode/IMPLEMENTATION.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Implementation plan

> **Build record.** The package lives in
> [`pi-extensions/pi-automode`](https://github.com/GaganSD/pi-extensions/tree/main/pi-automode)
> [`coding-agent-toolkit/pi-automode`](https://github.com/GaganSD/coding-agent-toolkit/tree/main/pi-automode)
> and is published as `@gagansd/pi-automode` (MIT).

## Scope being built
Expand Down
2 changes: 1 addition & 1 deletion pi-automode/docs/launch-decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ remains unverified, not assumed.

**Decision:** Publish name **`@gagansd/pi-automode`** (matching the
`@gagansd/pi-ask`, `@gagansd/pi-subagents`, `@gagansd/pi-web-search`
convention). The package is published from `pi-extensions` under **MIT** as
convention). The package is published from `coding-agent-toolkit` under **MIT** as
`0.1.0`. Publication covers the keyless/deterministic beta only:
**semantic enforcement stays off** and Jev remains shadow-only until the
risk-budget evidence in decision 3 exists. Publishing does not authorize a
Expand Down
Loading
Loading