pi-find-forks

KO | EN

gitlite — search

#python #hacktoberfest #react #ai #typescript #llm #machine-learning #rust #nodejs #macos #awesome #kubernetes #pytorch #mcp

(★ 16)

Scan GitHub forks of your repo for patterns worth upstreaming. A Pi extension.

pi-find-forks Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# pi-find-forks
### Mine GitHub forks for changes worth merging back upstream

**[Install](#install)** · **[Usage](#usage)** · **[How it works](#how-it-works)**

</div>

*Your repo has 500 forks. Most are abandoned. Some contain real fixes and features nobody ever upstreamed. find-forks reads them for you and points out what matters.*

An extension for **[pi](https://pi.dev/)**. Inspired by the workflow shape of [pi-autoresearch](https://github.com/davebcn87/pi-autoresearch) — an infrastructure extension plus a domain skill that drives an autonomous batch loop.

---

## What it does

You are a maintainer of `owner/repo`. You run `/find-forks` inside a clone of it. pi:

1. Enumerates the top N forks (default 30), ranked by stars.
2. For each fork, fetches commits + file-level stats from GitHub's compare API (one cheap call per fork).
3. Builds a one-paragraph **thesis** per fork: what is this fork trying to do?
4. Tags each fork (`perf`, `bugfix`, `platform:windows`, `feature:auth`, …) and scores **interestingness** (`noise` / `low` / `medium` / `high`).
5. Clusters analyses after every batch of 10: **2+ forks doing the same thing = a pattern worth upstreaming**.
6. Writes a living `find-forks.md` report with ranked upstream suggestions.

All state is persisted to `find-forks.jsonl` — append-only, resumable, human-readable.

## Prerequisites

- **[pi](https://pi.dev/)** installed.
- The **[`gh` CLI](https://cli.github.com/)** installed and authenticated (`gh auth status`).
- Run pi from inside a clone of the repo you maintain (`git remote get-url origin` points at `github.com/owner/repo`). You can also pass `repo` explicitly.

## Install

```bash
pi install git:github.com/HazAT/pi-find-forks
```

Or pin a version:

```bash
pi install git:github.com/HazAT/pi-find-forks@v0.1.0
```

<details>
<summary>Manual install</summary>

```bash
cp -r extensions/pi-find-forks ~/.pi/agent/extensions/
cp -r skills/find-forks-scan   ~/.pi/agent/skills/
```

Then `/reload` in pi.
</details>

## Usage

From inside a clone of your repo:

```
/find-forks start
```

The agent:
1. Calls `init_scan` (auto-detects owner/repo, fetches the top 30 forks by stars).
2. Writes `find-forks.md`.
3. Loops in batches of 10: `inspect_fork` → `record_analysis` → (rarely) `deep_inspect_fork`.
4. After each batch, clusters patterns via `record_pattern` and refreshes the report.
5. Continues until every candidate is analysed.

Free-form hints go straight to the agent:

```
/find-forks look at the 50 most recently active forks, I'm especially interested in parser fixes
```

### Subcommands

| Command | What it does |
|---------|--------------|
| `/find-forks start` | Start or resume a scan. |
| `/find-forks status` | One-line progress summary. |
| `/find-forks off` | Leave find-forks mode. Keeps `find-forks.jsonl`. |
| `/find-forks clear` | Delete `find-forks.jsonl` and reset. |

### Keyboard

| Shortcut | Action |
|----------|--------|
| `Ctrl+X` | Toggle the widget between compact and expanded (table of ranked forks + top patterns). |

## Tools the extension provides

| Tool | Purpose | Cost |
|------|---------|------|
| `init_scan` | Detect upstream, enumerate top-N forks. | ~1 API call + pagination |
| `inspect_fork` | Commits + file stats for one fork. | 1 API call (~600ms) |
| `deep_inspect_fork` | Same + truncated patches. Only used when necessary. | 1 API call |
| `record_analysis` | Persist thesis/tags/interestingness for a fork. | — |
| `record_pattern` | Persist a cross-fork cluster. | — |

## Output

**`find-forks.md`** — living report, rewritten each batch:

```markdown
# find-forks: karpathy/autoresearch

## Patterns
- **Apple Silicon / MPS adaptation** (4 forks)
  Suggested action: add an `--mps` flag to train.py and document the smaller-batch hyperparams.
- **Windows CRLF handling in prepare.py** (3 forks)
  Suggested action: normalise line endings at read time, add a Windows CI job.

## Upstream suggestions (ranked)
1. Adopt miolini/autoresearch-macos's MPS device selection in train.py — 4 forks converged here.
2. …

## Per-fork analyses
### miolini/autoresearch-macos [high] ★1984
Tags: `platform:macos`, `perf`
Tuned hyperparams + device selection for Apple Silicon / MPS. Self-contained, merge-ready.
```

**`find-forks.jsonl`** — raw log (`config` + `candidate` + `analysis` + `pattern` lines), append-only, survives restarts.

## How it works

```
┌────────────────────────────┐     ┌────────────────────────────┐
│  Extension (infrastructure)│     │  Skill (workflow)          │
│                            │     │                            │
│  init_scan / inspect_fork  │◄────│  detect repo               │
│  deep_inspect_fork         │     │  batch of 10 → inspect     │
│  record_analysis           │     │  deep-inspect if ambiguous │
│  record_pattern            │     │  cluster → record_pattern  │
│  widget + /find-forks      │     │  rewrite find-forks.md     │
└────────────────────────────┘     └────────────────────────────┘
```

Three-stage pipeline, each stage cheaper-first:

1. **List** (1 call) — top-N forks sorted by stargazers, newest, or oldest.
2. **Triage per fork** (1 call) — commits + file stats via `/compare`. Enough for most theses.
3. **Deep dive** (1 call, only when warranted) — full patches per file, truncated.

Cross-fork pattern detection happens *after* analyses land, working purely on the structured data the agent already recorded (tags, files, commits). No re-fetching.

## Design choices

- **`gh` CLI over raw API tokens.** One-line install, keychain-stored auth, no secrets in pi config.
- **JSONL + rebuildable markdown.** The agent can resume any scan by reading the jsonl — no in-memory-only state.
- **Batches of 10, not 1 or all.** Batching gives the agent room to notice patterns across recent forks while keeping progress visible. The extension auto-resumes if a turn ends mid-scan.
- **`stargazers` default sort.** Popular forks usually aren't the most interesting, but they're the ones least likely to be noise. For recency-focused runs, pass `sort_by="newest"`.

## Status

Early v0.1 — the core loop works. Not yet implemented (open to contributions):

- `find-forks-finalize` skill that turns patterns into branches / draft PRs.
- Sibling-fork mode (you're on a fork; scan *other* forks of the same upstream).
- Browser dashboard export.

## License

MIT

pi-find-forks

pi-find-forks Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

pi-find-forks

pi-find-forks Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README