{"_id":"@ariesfish/pi-goal","_rev":"3-4c442ea91dbfb981a4e5e31d19456672","name":"@ariesfish/pi-goal","dist-tags":{"latest":"0.4.0"},"versions":{"0.2.0":{"name":"@ariesfish/pi-goal","version":"0.2.0","keywords":["pi-package","pi","pi-extension","goal","experiment","optimization","benchmark","coding-agent"],"author":{"name":"ariesfish","email":"zzlyldy@gmail.com"},"license":"MIT","_id":"@ariesfish/pi-goal@0.2.0","maintainers":[{"name":"ariesfish","email":"zzlyldy@gmail.com"}],"homepage":"https://github.com/ariesfish/pi-goal#readme","bugs":{"url":"https://github.com/ariesfish/pi-goal/issues"},"pi":{"skills":["./skills"],"extensions":["./extensions"]},"dist":{"shasum":"1f4450b9dcc771afa2c7d90ed9b4f12d392c70b2","tarball":"https://registry.npmjs.org/@ariesfish/pi-goal/-/pi-goal-0.2.0.tgz","fileCount":65,"integrity":"sha512-7WjrX0pFq4Ywlco8fcSjyS+JieEtU7o4waUIr1pA6jq1l+tlzNylQPVf3pmbXb9T5eckFG2oyf3GoItUjU4O6w==","signatures":[{"sig":"MEUCIFZ5JU9Ltk2Cb9EdrSpVYMb3iLhGQuefYMsFgfRggAeiAiEA4sn0zYoYk5g3gYTHTdy2MqR6RR98UYf7vtnPLuAKCmM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":295066},"type":"module","engines":{"node":">=22"},"gitHead":"6da4f2e670e493181cb1627448637292d8f1819b","scripts":{"test":"node --experimental-strip-types --test \"tests/**/*.test.mjs\"","test:finalize":"bash tests/scripts/finalize_test.sh"},"_npmUser":{"name":"ariesfish","email":"zzlyldy@gmail.com"},"repository":{"url":"git+https://github.com/ariesfish/pi-goal.git","type":"git"},"_npmVersion":"11.6.2","description":"Autonomous experiment loop for pi — run, measure, keep or discard. Inspired by karpathy/autoresearch.","directories":{},"_nodeVersion":"24.11.1","_hasShrinkwrap":false,"packageManager":"pnpm@10.28.2","devDependencies":{"typescript":"^6.0.3","@types/node":"^25.9.1","@sinclair/typebox":"^0.34.41","@earendil-works/pi-ai":"^0.75.0","@earendil-works/pi-tui":"^0.75.0","@earendil-works/pi-coding-agent":"^0.75.0"},"peerDependencies":{"@sinclair/typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-goal_0.2.0_1779781198075_0.5401269089416945","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@ariesfish/pi-goal","version":"0.3.0","keywords":["pi-package","pi","pi-extension","goal","experiment","optimization","benchmark","coding-agent"],"author":{"name":"ariesfish","email":"zzlyldy@gmail.com"},"license":"MIT","_id":"@ariesfish/pi-goal@0.3.0","maintainers":[{"name":"ariesfish","email":"zzlyldy@gmail.com"}],"homepage":"https://github.com/ariesfish/pi-goal#readme","bugs":{"url":"https://github.com/ariesfish/pi-goal/issues"},"pi":{"skills":["./skills"],"extensions":["./extensions"]},"dist":{"shasum":"f473a63623d233dbccf67b4ad7d002f52611422f","tarball":"https://registry.npmjs.org/@ariesfish/pi-goal/-/pi-goal-0.3.0.tgz","fileCount":65,"integrity":"sha512-RAiIliCU7EFI+iMmOTdFC6fIjeX+pBM5IB3tHwGEd483nScX9IWsMfzzirEJnyYSOuoufiKdH6XvuDk9IWocMQ==","signatures":[{"sig":"MEUCIQClwWnCSFIepCcgA+m8AroIsWLCGazvnBmzt7/yNkgMnQIgIPi1FyHh6NfkpydRaI8mA77z7LfAfMNujYOzGqPACCE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@ariesfish%2fpi-goal@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":295386},"type":"module","engines":{"node":">=22"},"gitHead":"46c65c68893e3fd0f82c0fd744aa32be2b7efa4e","scripts":{"test":"node --experimental-strip-types --test \"tests/**/*.test.mjs\"","test:finalize":"bash tests/scripts/finalize_test.sh"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:b93d009a-b8d0-400e-aafd-97d3c40afd16"}},"repository":{"url":"git+https://github.com/ariesfish/pi-goal.git","type":"git"},"_npmVersion":"11.15.0","description":"Autonomous experiment loop for pi — run, measure, keep or discard. Inspired by karpathy/autoresearch.","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"packageManager":"pnpm@10.28.2","devDependencies":{"typescript":"^6.0.3","@types/node":"^25.9.1","@sinclair/typebox":"^0.34.41","@earendil-works/pi-ai":"^0.75.0","@earendil-works/pi-tui":"^0.75.0","@earendil-works/pi-coding-agent":"^0.75.0"},"peerDependencies":{"@sinclair/typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-goal_0.3.0_1779784465297_0.8654632894562173","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@ariesfish/pi-goal","version":"0.4.0","type":"module","description":"Autonomous experiment loop for pi — run, measure, keep or discard. Inspired by karpathy/autoresearch.","keywords":["pi-package","pi","pi-extension","goal","experiment","optimization","benchmark","coding-agent"],"license":"MIT","author":{"name":"ariesfish","email":"zzlyldy@gmail.com"},"homepage":"https://github.com/ariesfish/pi-goal#readme","repository":{"type":"git","url":"git+https://github.com/ariesfish/pi-goal.git"},"bugs":{"url":"https://github.com/ariesfish/pi-goal/issues"},"engines":{"node":">=22"},"packageManager":"pnpm@10.28.2","pi":{"extensions":["./extensions"],"skills":["./skills"]},"scripts":{"test":"node --experimental-strip-types --test \"tests/**/*.test.mjs\"","test:finalize":"bash tests/scripts/finalize_test.sh"},"peerDependencies":{"@earendil-works/pi-ai":"*","@earendil-works/pi-coding-agent":"*","@earendil-works/pi-tui":"*","@sinclair/typebox":"*"},"devDependencies":{"@earendil-works/pi-ai":"^0.75.0","@earendil-works/pi-coding-agent":"^0.75.0","@earendil-works/pi-tui":"^0.75.0","@sinclair/typebox":"^0.34.41","@types/node":"^25.9.1","typescript":"^6.0.3"},"gitHead":"c7982245f2d1b09f9ff90060d88ec5d78ec60ce0","_id":"@ariesfish/pi-goal@0.4.0","_nodeVersion":"24.15.0","_npmVersion":"11.15.0","dist":{"integrity":"sha512-OcSfctsfzytBtOMrrku2hGtenlBeKbqGoARGnciTj2MQwDSM7a88/qsVLF0RxUlEiIglNGSG2wrALktZQJnyzQ==","shasum":"e6c4c82b654b4cf49055e8f8720591a6c51cee2a","tarball":"https://registry.npmjs.org/@ariesfish/pi-goal/-/pi-goal-0.4.0.tgz","fileCount":62,"unpackedSize":296007,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@ariesfish%2fpi-goal@0.4.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICgKie1QDazojRDp1CLhap8VXRZTxfDUe8eOG3Ljt+4hAiEAvBCDyrQvXI67BR9p0TRzsHUV9bxxJDpzewOVGMi0IYM="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:b93d009a-b8d0-400e-aafd-97d3c40afd16"}},"directories":{},"maintainers":[{"name":"ariesfish","email":"zzlyldy@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-goal_0.4.0_1779789889405_0.5658399401226402"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-26T07:39:57.909Z","modified":"2026-05-26T10:04:49.851Z","0.2.0":"2026-05-26T07:39:58.215Z","0.3.0":"2026-05-26T08:34:25.436Z","0.4.0":"2026-05-26T10:04:49.550Z"},"bugs":{"url":"https://github.com/ariesfish/pi-goal/issues"},"author":{"name":"ariesfish","email":"zzlyldy@gmail.com"},"license":"MIT","homepage":"https://github.com/ariesfish/pi-goal#readme","keywords":["pi-package","pi","pi-extension","goal","experiment","optimization","benchmark","coding-agent"],"repository":{"type":"git","url":"git+https://github.com/ariesfish/pi-goal.git"},"description":"Autonomous experiment loop for pi — run, measure, keep or discard. Inspired by karpathy/autoresearch.","maintainers":[{"name":"ariesfish","email":"zzlyldy@gmail.com"}],"readme":"<div align=\"center\">\n\n# pi-goal\n### Autonomous experiment loops for pi\n**[Install](#install)** · **[Usage](#usage)** · **[Reference](#reference)**\n\n</div>\n\n*pi-goal lets pi try an idea, measure it, keep improvements, revert regressions, and continue from durable state.*\n\nUse it for any measurable optimization target: test speed, bundle size, training loss, build time, Lighthouse score, or custom benchmarks.\n\n---\n\n## Install\n\n```bash\npi install npm:@ariesfish/pi-goal\n```\n\nManual install:\n\n```bash\ncp -r extensions/pi-goal ~/.pi/agent/extensions/\ncp -r skills/goal-create ~/.pi/agent/skills/\ncp -r skills/goal-finalize ~/.pi/agent/skills/\ncp -r skills/goal-hooks ~/.pi/agent/skills/\n```\n\nThen run `/reload` in pi.\n\n---\n\n## Usage\n\n### Start a loop\n\n```text\n/skill:goal-create\n```\n\nThe skill asks for, or infers:\n\n- goal\n- benchmark command\n- primary metric and direction\n- files in scope\n- constraints\n\nIt creates a goal branch, writes `goal.md` and `goal.sh`, runs the baseline, then starts iterating.\n\n### Run directly with `/goal`\n\n```text\n/goal optimize unit test runtime, monitor correctness\n/goal model training, run 5 minutes of train.py and track validation loss\n```\n\nUseful subcommands:\n\n| Command | Purpose |\n|---|---|\n| `/goal <text>` | Start or resume goal mode |\n| `/goal off` | Leave goal mode; keep persisted files |\n| `/goal clear` | Delete `goal.jsonl` and reset state |\n| `/goal reinit` | Start a new comparable experiment with a fresh baseline |\n| `/goal select <goal-id>` | Switch active research under `.goal/researches/` |\n| `/goal export` | Open the live browser dashboard |\n\n### The loop\n\npi edits code, commits candidates, calls `run_goal`, then calls `log_goal`:\n\n```text\nedit → commit → run_goal → log_goal → keep or revert → repeat\n```\n\nResults are appended to `goal.jsonl`. The current plan and learnings live in `goal.md`, so a fresh agent can resume after restarts or context compaction.\n\n### Finalize results\n\n```text\n/skill:goal-finalize\n```\n\nThis reads `goal.jsonl`, groups kept runs into logical changesets, asks for approval, then creates one reviewable branch per group from the merge base.\n\n---\n\n## What it installs\n\n### Extension tools\n\n| Tool | Purpose |\n|---|---|\n| `init_goal` | Initialize the active research and first experiment |\n| `start_goal` | Open a new comparable experiment with a fresh baseline |\n| `run_goal` | Time a command, capture output, parse `METRIC name=value` lines |\n| `log_goal` | Record the run, keep improvements, revert failures/regressions |\n| `validate_goal` | Check goal files, metric output, checks, and workspace safety |\n\n### Skills\n\n| Skill | Purpose |\n|---|---|\n| `goal-create` | Set up and start an optimization loop |\n| `goal-finalize` | Turn a noisy goal branch into clean review branches |\n| `goal-hooks` | Help author optional `goal.hooks/before.sh` and `after.sh` scripts |\n\n### Files used by a loop\n\n| File | Purpose |\n|---|---|\n| `goal.md` | Goal, metric, scope, constraints, attempts, learnings |\n| `goal.sh` | Benchmark script; should output `METRIC name=value` |\n| `goal.jsonl` | Append-only run journal |\n| `goal.checks.sh` | Optional correctness checks after successful benchmarks |\n| `goal.ideas.md` | Optional backlog of promising ideas |\n| `goal.hooks/` | Optional scripts fired before/after iterations |\n\n---\n\n## UI\n\n- Status widget above the editor: `🎯 goal 12 runs 8 kept │ ★ total_µs: 15,200 (-12.3%) │ conf: 2.1×`\n- `Ctrl+Shift+T`: expand/collapse inline dashboard\n- `Ctrl+Shift+F`: fullscreen scrollable dashboard\n- `/goal export`: live browser dashboard with chart and share card\n\nOverride shortcuts in `<agent-dir>/extensions/pi-goal.json`:\n\n```json\n{\n  \"shortcuts\": {\n    \"toggleDashboard\": \"ctrl+shift+y\",\n    \"fullscreenDashboard\": null\n  }\n}\n```\n\nUse `null` to disable a shortcut.\n\n---\n\n## Reference\n\n### Benchmark contract\n\n`goal.sh` should exit non-zero on benchmark failure and print the primary metric as:\n\n```text\nMETRIC total_ms=123.4\n```\n\nSecondary metrics can use the same format:\n\n```text\nMETRIC bundle_kb=42.1\n```\n\n### Backpressure checks\n\nCreate executable `goal.checks.sh` to block unsafe keeps:\n\n```bash\n#!/bin/bash\nset -euo pipefail\npnpm test\npnpm typecheck\n```\n\nChecks run after a benchmark exits 0. Their runtime does not affect the primary metric. Failures are logged as `checks_failed` and code changes are reverted.\n\n### Confidence score\n\nAfter 3+ runs in an experiment, pi-goal estimates benchmark noise with Median Absolute Deviation (MAD):\n\n```text\nconfidence = |best improvement| / MAD\n```\n\n| Score | Meaning |\n|---|---|\n| `≥ 2.0×` | likely real improvement |\n| `1.0–2.0×` | above noise but marginal |\n| `< 1.0×` | within noise; rerun to confirm |\n\nThe score is advisory. It never auto-discards.\n\n### Configuration\n\nCreate `goal.config.json` in the pi session directory:\n\n```json\n{\n  \"workingDir\": \"/path/to/project\",\n  \"maxIterations\": 50\n}\n```\n\n| Field | Purpose |\n|---|---|\n| `workingDir` | Override where goal files, commands, and git operations run |\n| `maxIterations` | Stop after this many runs until a new experiment is started |\n\n### Hooks\n\nOptional executable hooks live in `goal.hooks/`:\n\n| Hook | Fires | Typical use |\n|---|---|---|\n| `before.sh` | before activation and after each completed run | fetch research, rotate ideas, prime context |\n| `after.sh` | after each `log_goal` | append learnings, notify, tag winners |\n\nHooks receive one JSON object on stdin, write steer text on stdout, timeout after 30s, and append hook entries to `goal.jsonl`. See [`skills/goal-hooks/examples/`](skills/goal-hooks/examples/) for complete scripts.\n\n---\n\n## Example targets\n\n| Target | Metric | Command |\n|---|---|---|\n| Test speed | seconds ↓ | `pnpm test` |\n| Bundle size | KB ↓ | `pnpm build && du -sb dist` |\n| Training | val loss ↓ | `uv run train.py` |\n| Build speed | seconds ↓ | `pnpm build` |\n| Lighthouse | score ↑ | `lighthouse http://localhost:3000 --output=json` |\n\n---\n\n## Prerequisites\n\n- pi installed and configured\n- an LLM provider API key\n- a benchmark command with a numeric metric\n\nGoal loops can run for a long time. Use provider-side budgets and `maxIterations` to cap cost.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}