{"id":50233238,"url":"https://github.com/martelogan/pi-autoclanker","last_synced_at":"2026-05-30T22:01:49.330Z","repository":{"id":350970078,"uuid":"1208958769","full_name":"martelogan/pi-autoclanker","owner":"martelogan","description":"Autoclanker pi extension for Bayesian Agent experiment loops","archived":false,"fork":false,"pushed_at":"2026-05-28T00:42:44.000Z","size":1029,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T02:22:01.924Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/martelogan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-13T00:39:26.000Z","updated_at":"2026-05-28T00:42:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/martelogan/pi-autoclanker","commit_stats":null,"previous_names":["martelogan/pi-autoclanker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/martelogan/pi-autoclanker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martelogan%2Fpi-autoclanker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martelogan%2Fpi-autoclanker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martelogan%2Fpi-autoclanker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martelogan%2Fpi-autoclanker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/martelogan","download_url":"https://codeload.github.com/martelogan/pi-autoclanker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martelogan%2Fpi-autoclanker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33711018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-26T19:00:32.259Z","updated_at":"2026-05-30T22:01:49.324Z","avatar_url":"https://github.com/martelogan.png","language":"TypeScript","funding_links":[],"categories":["Extensions"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg height=\"120\" alt=\"pi-autoclanker logo\" src=\"docs/assets/pi-autoclanker-logo.svg\" /\u003e\n\n# pi-autoclanker\n\n### TypeScript-native pi extension for autoclanker\n\n[![Node](https://img.shields.io/badge/node-22%2B-339933?logo=node.js\u0026logoColor=white)](https://nodejs.org/)\n[![Interface](https://img.shields.io/badge/interface-pi%20extension-143D59)](#quick-start)\n[![Backend](https://img.shields.io/badge/backend-autoclanker-214E34)](https://github.com/martelogan/autoclanker)\n\n**[Install](#install)** ·\n**[Quick start](#quick-start)** ·\n**[Clankerbench](#clankerbench)** ·\n**[Mental model](#mental-model)** ·\n**[Live surfaces](#live-surfaces)** ·\n**[Commands](#commands)** ·\n**[Tools](#tools)** ·\n**[Skills](#skills)** ·\n**[Hooks](#hooks)** ·\n**[Start simple](#start-simple)** ·\n**[Optimization loop](#optimization-loop)** ·\n**[Why this is different](#why-this-is-different)** ·\n**[Files \u0026 output](#files--output)** ·\n**[Developer](#developer)**\n\n\u003c/div\u003e\n\n*Start from a rough optimization goal, explore short ideas or full plan files in parallel, keep the eval surface fixed, and let `autoclanker` drive the actual fit loop.*\n\n`pi-autoclanker` is the thin pi layer for\n[autoclanker](https://github.com/martelogan/autoclanker). It is meant to feel\nsimple from the pi side:\n\n- take a goal and rough ideas,\n- write a small resumable session surface into your project,\n- shell out to `autoclanker` for preview, apply, ingest, fit, suggest, and\n  commit recommendation.\n\nIf you like the optimization flow of\n[Autoresearch](https://github.com/karpathy/autoresearch) or\n[cEvolve](https://github.com/jnormore/cevolve), this is the same\n`idea -\u003e explore -\u003e rethink` routine, but supported by Bayesian typed priors and\nthe snapshot-eval outer loop harness provided by `autoclanker`, so plans can\nstay explicit, be explored in parallel, and be judged against locked eval\nfeedback instead of dissolving into one long prompt thread.\n\n## Install\n\nYou need two things:\n\n1. `autoclanker` on your machine\n2. the `pi-autoclanker` extension installed into pi\n\nInstall `autoclanker`:\n\n```bash\nuv tool install git+https://github.com/martelogan/autoclanker.git\n# or: pip install git+https://github.com/martelogan/autoclanker.git\n```\n\nInstall the extension:\n\n```bash\npi install https://github.com/martelogan/pi-autoclanker\n```\n\nFor local development instead of the published repo:\n\n```bash\npi install /absolute/path/to/pi-autoclanker\n```\n\n## Quick start\n\nInside a real project:\n\n```bash\n/autoclanker start Improve parser throughput without losing context quality.\n```\n\nThat is the shortest useful path to **initialize or resume the session**. It\nmaterializes the project-local files, previews typed beliefs through\n`autoclanker`, and refreshes the widget/dashboard. It does not by itself launch\nan autonomous coding loop. After the session starts, give the agent normal\ninstructions to use the `autoclanker_*` tools, implement candidates, run the\nfixed eval surface, ingest measurements, fit, suggest, and repeat until a\nmeasured keep/reject/blocker result exists.\n\nFor an unattended long run, use the execution handoff instead:\n\n```bash\n/autoclanker run --overnight Improve parser throughput without losing context quality.\n```\n\n`run --overnight` initializes or resumes the same files, sets `runIntensity` to\n`mega`, records an unattended execution policy, and returns a handoff prompt\nthat tells the supervising agent not to ask late clarification questions. After\nstartup, uncertainty should become assumptions, risks, pending comparison\nqueries, or proposal notes. See [`docs/HEADLESS_AGENT.md`](docs/HEADLESS_AGENT.md)\nfor non-Pi and enterprise/cloud supervisor usage.\n\nIf you do not provide a real eval command yet, `pi-autoclanker` can generate a\ndefault checked-in `autoclanker.eval.sh` stub so the session starts immediately\nand stays inspectable.\n\nIf you want a checked-in intake file, store rough ideas directly or in\n`autoclanker.ideas.json`:\n\n```json\n{\n  \"goal\": \"Improve parser throughput without losing context quality.\",\n  \"ideas\": [\n    \"Cache repeated matcher work.\",\n    { \"id\": \"context_plan\", \"path\": \"plans/context-pair-plan.md\" }\n  ],\n  \"constraints\": [\"Keep output quality stable.\"]\n}\n```\n\nUse plain strings for quick ideas, and point at the file directly when one idea\nis already a checked-in markdown or text plan. This is one of the main harness\nadvantages: several rough ideas or fully-fledged plans can stay explicit, be\nexplored in parallel when practical, and be measured against the same locked\neval feedback instead of getting flattened into a single prompt history.\n\nThat intake file is only a convenience surface, not the minimum required input.\n`autoclanker.beliefs.json` remains the generated belief surface. When you are\nready for explicit multi-path comparison, add `autoclanker.frontier.json` and\nuse the frontier commands instead of burying alternative paths in prompt\nhistory. `pi-autoclanker` keeps a concise local label for a plan-backed idea,\nbut passes a bounded canonicalization view to `autoclanker` while keeping file\npath and digest provenance locally in `autoclanker.beliefs.json`.\n\nKeep the starter file intentionally small. If you later want to capture risks,\npairwise preferences, or confidence hints, let\n`/skill:autoclanker-advanced-beliefs` pull those out after the first preview\ninstead of expanding the starter file up front.\n\nIf you already want explicit early lanes, keep that as a later-stage\n`pathways` shape instead of front-loading it into the first intake example. See\n[`examples/parser-demo-expanded/autoclanker.ideas.json`](examples/parser-demo-expanded/autoclanker.ideas.json)\nfor the explicit-lane form and the expanded demo.\n\nFor domain work, do not rely on the package demo surface. Put the domain-local\ntyped surface and explicit candidate lanes directly in `autoclanker.ideas.json`\nor `autoclanker.frontier.json`. A compact domain intake can carry:\n\n```json\n{\n  \"goal\": \"Improve a domain-specific hot path.\",\n  \"surface_overlay\": {\n    \"registry\": {\n      \"domain.request_boundary\": {\n        \"states\": [\"baseline\", \"precompute_settings\"],\n        \"default_state\": \"baseline\",\n        \"description\": \"Move repeated request setup work earlier.\",\n        \"surface_kind\": \"mutation_family\",\n        \"semantic_level\": \"strategy\",\n        \"materializable\": false,\n        \"origin\": \"idea_file\"\n      }\n    }\n  },\n  \"ideas\": [{ \"id\": \"settings_boundary\", \"text\": \"Precompute settings once.\" }],\n  \"pathways\": [\n    {\n      \"id\": \"settings_boundary\",\n      \"idea_ids\": [\"settings_boundary\"],\n      \"genotype\": [\n        {\n          \"gene_id\": \"domain.request_boundary\",\n          \"state_id\": \"precompute_settings\"\n        }\n      ]\n    }\n  ]\n}\n```\n\nWhen a frontier has more than one lane, `ingest-eval` now requires an explicit\n`--candidate-id` or unambiguous `--family-id`; this prevents measurements from\nbeing attributed to a generic current workspace lane. That isolation is per\nmeasurement, not per whole run: after each fit/suggest cycle the frontier can\nkeep, drop, split, or merge pathways and evaluate those merged candidates under\nthe same locked eval surface.\n\nIf you want a guided setup instead of typing everything into a slash command,\nstart with:\n\n```bash\n/skill:autoclanker-create\n```\n\nFor the LLM-assisted intake path, start with rough notes rather than trying to\nhand-author Bayes syntax:\n\n```text\nI want to start a pi-autoclanker run from these rough optimization notes.\nAsk at most three clarifying questions if needed, then create or update\nautoclanker.ideas.json with:\n\n- a short goal\n- the rough ideas as strings, markdown-plan paths, or rich idea objects\n- the fixed eval command or a checked-in autoclanker.eval.sh surface\n- domain-local surface_overlay genes when this is not the package demo domain\n- explicit pathways with genotype entries for the first lanes worth comparing\n\nAfter writing the file, run autoclanker_preview_beliefs, show me the typed\nbelief/frontier preview, revise once if the lanes are wrong, then apply and\nstart the measured loop. For multi-candidate frontiers, bind every eval ingest\nto a candidateId or unambiguous familyIds selector.\n```\n\nThat discussion phase is intentionally lightweight. The LLM should help turn\nloose markdown, JSON snippets, benchmark notes, and operator constraints into a\nreviewable `autoclanker.ideas.json`; `pi-autoclanker` then keeps the resulting\nbeliefs, frontier, eval surface, progress snapshot, and history inspectable on\ndisk instead of leaving the setup hidden in chat. During long runs, use the\nwidget, `/autoclanker status`, and `autoclanker.progress.json` to see the active\ncommand, current lane, iteration count, trust/eval state, and latest measured\nsummary.\n\nMost runs should keep a finite `maxIterations` so weak searches converge and\nsummarize instead of spinning. When the intent is a supervised \"go as far as\npossible\" run, use `/autoclanker run --overnight`, set\n`runIntensity: \"mega\"` in `autoclanker.config.json` or\n`autoclanker.ideas.json`, or pass `--run-intensity mega` / `--mega`. Mega mode\nkeeps the locked eval surface and candidate binding rules, but disables the\nwrapper's max-iteration stop so the supervisor can continue until all valuable\nlanes have a measured keep/reject/blocker result.\n\nFor a preseeded benchmark workspace, start from the directory that contains the\nsession files and point at the existing intake file:\n\n```bash\n/autoclanker start --ideas-input autoclanker.ideas.json\n```\n\nThen paste the workspace prompt, for example:\n\n```text\nRead README.md, autoclanker.md, autoclanker.ideas.json, and the benchmark\nbriefs first. Use the active pi-autoclanker session and its autoclanker_* tools.\nTreat bash autoclanker.eval.sh as the fixed eval surface. Do not stop until you\nhave a measured keep/reject/blocker result.\n```\n\nFor unattended runs, prefer:\n\n```bash\n/autoclanker run --overnight --ideas-input autoclanker.ideas.json\n```\n\n## Mental model\n\nThe beginner mental model should stay small:\n\n![pi-autoclanker loop](docs/assets/pi-autoclanker-mental-model.svg)\n\n- start from a direct goal or an optional `autoclanker.ideas.json`\n- let `autoclanker` preview those ideas as typed beliefs\n- evaluate one or more candidate lanes or pathways\n- ingest, fit, and ask what to compare next\n\nOne vocabulary layer is enough to use the tool well:\n\n![pi-autoclanker structure](docs/assets/pi-autoclanker-structure.svg)\n\n- `optimization lever (gene)`: one explicit knob the upstream adapter exposes\n- `setting (state)`: one concrete value of that lever\n- `candidate lane` or `pathway`: one concrete combination being evaluated\n- `frontier`: the explicit set of lanes under comparison\n- `belief`: a claim about one setting, relation, risk, or preference\n\nThe engine learns over explicit candidate features and relations, not hidden\nprompt state. Status may show backend names or comparison focus, but those are\nevidence and debugging details, not required user inputs.\n\nSee [`docs/MENTAL_MODEL.md`](docs/MENTAL_MODEL.md) for the fuller plain-language\nversion, including when advanced structure is worth adding and what beginners\ncan safely ignore.\n\n## What’s included\n\n| Surface | What it gives you |\n| --- | --- |\n| Extension | pi tools plus the `/autoclanker` command family |\n| Skills | beginner creation, advanced belief authoring, and session review |\n| Hooks | optional executable before/after eval sidecars for context refresh, notifications, and learnings |\n| Local files | resumable checked-in session files plus an optional `autoclanker.ideas.json` intake file |\n| Status surface | trust digest, backend choice, and next concrete comparison without digging through raw JSON |\n| Clankerbench contracts | generic staged benchmark manifest, schema, TypeScript types, and provider example |\n| Upstream artifacts | `.autoclanker/\u003csession\u003e/` JSON, reports, and charts from `autoclanker` |\n\nThe fastest way to understand the repo now is:\n\n- [`examples/targets/parser-quickstart`](examples/targets/parser-quickstart) for\n  a real packaged parser target and benchmark\n- [`examples/minimal`](examples/minimal) for the smallest kickoff shape\n- [`examples/parser-demo-expanded`](examples/parser-demo-expanded) for a fuller\n  worked session after the extension has already materialized local files\n\n## Clankerbench\n\n`clankerbench` is the generic benchmark framework contract that lets a project\ndescribe a staged benchmark harness without putting project-specific logic into\nthe benchmark contract. It defines the stage vocabulary, manifest schema, and\nprovider boundary for flows like:\n\n```text\nbootstrap -\u003e cohort -\u003e materialize -\u003e analyze -\u003e spec\n                                      |         |\n                                      v         v\n                                   context -\u003e eval -\u003e compare\n                                      |\n                                      v\n                            distill -\u003e session\n```\n\nThe current support is intentionally additive and contract-first:\n\n- [`docs/CLANKERBENCH.md`](docs/CLANKERBENCH.md) describes the methodology and\n  provider boundary.\n- [`schemas/clankerbench.pipeline.schema.json`](schemas/clankerbench.pipeline.schema.json)\n  defines the JSON manifest.\n- [`src/clankerbench.ts`](src/clankerbench.ts) exports the stage constants,\n  TypeScript types, and lightweight validation helper.\n- [`examples/clankerbench-mini`](examples/clankerbench-mini) shows the manifest\n  shape for a command-backed provider.\n\nProject-specific harnesses should plug in behind provider commands or modules.\nAny compatible outer-loop engine can then consume the declared artifacts,\ncontext brief, guardrails, hooks, stop conditions, and eval command;\n`clankerbench` explains how the benchmark surface was selected, prepared,\npackaged, researched, and checked.\n\n`pi-autoclanker command start` auto-detects `clankerbench.manifest.json` in the\nworkspace, or accepts `--clankerbench-manifest \u003cpath\u003e`. When present, the\nmanifest can seed the session goal, fixed eval command, guardrails,\nmax-iteration budget, research sources, and status/evidence paths while\nproject-specific benchmark logic remains behind provider commands.\n\n## Live surfaces\n\nThe wrapper now keeps one shared live model and exposes it through four views:\n\n- a compact widget that appears when the current cwd contains an autoclanker\n  session (i.e. `autoclanker.config.json`, `autoclanker.md`, or\n  `autoclanker.history.jsonl` is present at the project root). In directories\n  without an autoclanker session the widget stays hidden so pi boots silently\n  outside of optimization work; `/autoclanker` and the keyboard shortcuts\n  below still surface the widget on demand from anywhere.\n- `Ctrl+X` or `Ctrl+Alt+X` for an expanded inline dashboard\n- `Ctrl+Shift+X` or `Ctrl+Alt+Shift+X` for a fullscreen overlay\n- `/autoclanker export` for the machine-readable bundle and, inside the\n  interactive extension, a browser dashboard that auto-refreshes while the\n  extension is driving work\n\nThose views stay grounded in the same four plain-language briefs:\n\n- `Prior Brief`: what the run started with and why those lanes exist\n- `Run Brief`: what is being tested now, who leads, and what comparison comes next\n- `Posterior Brief`: what the evidence changed after fit and suggest\n- `Proposal Brief`: what is ready, blocked, deferred, or waiting for approval\n\nThe expanded views include both a frontier decision table and a proposal table.\nThat is where promoted lanes, pending merges, blocked lanes, and recommended or\napproval-ready proposals stay visible while a long run continues.\n\nThe browser dashboard and widget stack do not add a second engine. They are\njust richer views over the same local files and upstream `autoclanker`\nartifacts. When upstream `autoclanker` exposes `session review-bundle`,\n`pi-autoclanker` prefers that normalized review model and mirrors it through\nstatus, export, the widget stack, lineage, trust, and next-action panels while\nkeeping a local-derived fallback for older sessions. Partial upstream review\ndata is merged with local frontier and artifact state rather than replacing it,\nand the wrapper does not leave behind extra `dashboard_payload.json`-style\nfiles by default.\n\nDuring pi context compaction, the extension emits a deterministic summary from\n`autoclanker.md`, beliefs, frontier, proposals, hooks, and recent local history\ninstead of relying on an LLM to rediscover the run state from chat. New turns\nalso receive a short active-session prompt pointer so the agent resumes from the\nproject-local files rather than from stale conversation memory.\n\n## Commands\n\n`pi-autoclanker` exposes one slash-command family:\n\n| Command | Description |\n| --- | --- |\n| `/autoclanker run \u003cgoal\u003e` | Initialize or resume an unattended/headless execution handoff; use `--overnight` for long autonomous runs. |\n| `/autoclanker start \u003cgoal\u003e` | Initialize or resume the project-local session from a goal; it does not launch autonomous coding by itself. |\n| `/autoclanker resume` | Mark the current session active again without changing beliefs. |\n| `/autoclanker status` | Summarize the current local session files plus upstream review, trust, lineage, and next-action state. |\n| `/autoclanker frontier-status` | Show local frontier state plus upstream frontier summary. |\n| `/autoclanker compare-frontier` | Persist or reuse `autoclanker.frontier.json` and compare explicit pathways upstream. |\n| `/autoclanker merge-pathways` | Merge selected pathways into the local frontier file and re-rank them upstream. |\n| `/autoclanker off` | Disable the current session without deleting resumable files. |\n| `/autoclanker clear` | Delete local `pi-autoclanker` files and the upstream session root. |\n| `/autoclanker export` | Export the current session bundle as machine-readable JSON, including the normalized review bundle; inside the interactive extension it also opens the browser dashboard. |\n\nUseful examples:\n\n```text\n/autoclanker start Reduce API latency without hurting correctness.\n/autoclanker run --overnight Reduce API latency without hurting correctness.\n/autoclanker compare-frontier\n/autoclanker status\n/autoclanker export\n/autoclanker off\n```\n\n## Tools\n\nThese are the extension tools available to pi:\n\n| Tool | Description |\n| --- | --- |\n| `autoclanker_init_session` | Bootstrap local session files and upstream session state. |\n| `autoclanker_session_status` | Read resumable local state and ask `autoclanker` for upstream status. |\n| `autoclanker_frontier_status` | Read the local frontier file and ask `autoclanker` for upstream frontier status. |\n| `autoclanker_preview_beliefs` | Preview or canonicalize rough ideas before apply. |\n| `autoclanker_apply_beliefs` | Apply the current belief batch through `autoclanker`. |\n| `autoclanker_ingest_eval` | Run optional eval hooks, execute the checked-in eval surface under the locked upstream eval contract, and ingest its JSON result. |\n| `autoclanker_fit` | Fit the active upstream `autoclanker` session. |\n| `autoclanker_suggest` | Request the next suggestion, optionally against an explicit candidate pool. |\n| `autoclanker_compare_frontier` | Persist or reuse `autoclanker.frontier.json`, then compare explicit pathways through upstream `autoclanker`. |\n| `autoclanker_merge_pathways` | Merge selected pathways into the local frontier file and ask upstream `autoclanker` to re-rank them. |\n| `autoclanker_recommend_commit` | Ask `autoclanker` for a commit recommendation. |\n\nThe point of these tools is not to reimplement `autoclanker` in TypeScript. The\nextension stays thin and inspectable, while `autoclanker` remains the Bayesian\nsource of truth.\n\n## Skills\n\n| Skill | Purpose |\n| --- | --- |\n| `autoclanker-create` | Start from a direct goal or optional `autoclanker.ideas.json`, write the local files, preview beliefs, and initialize the session. |\n| `autoclanker-autonomous-supervisor` | Drive unattended or headless execution from the generated handoff without asking late clarification questions. |\n| `autoclanker-advanced-beliefs` | Turn rough ideas into compact advanced JSON beliefs by starting with up to three high-yield follow-up questions per round when the beginner path is no longer enough. |\n| `autoclanker-hooks` | Add optional `autoclanker.hooks/before-eval.sh` and `after-eval.sh` scripts for eval-adjacent side effects without turning hooks into a second optimizer. |\n| `autoclanker-review` | Read the current session and summarize it through the Prior / Run / Posterior / Proposal briefs in plain language. |\n\nThe common flow is:\n\n- use `autoclanker-create` first,\n- keep rough ideas as plain strings at first,\n- move to `autoclanker-advanced-beliefs` only when risks, relations, or\n  graph-structured priors actually matter.\n\n## Hooks\n\n`pi-autoclanker` also has a small lifecycle hook surface inspired by recent\n[`pi-autoresearch`](https://github.com/martelogan/pi-autoresearch) workflow\nimprovements, adapted to autoclanker's eval-contract model:\n\n```text\nautoclanker.hooks/\n  before-eval.sh    # optional, executable, runs before autoclanker.eval.sh\n  after-eval.sh     # optional, executable, runs after upstream eval ingest\n```\n\nEach hook receives one JSON object on stdin with workspace, session, candidate,\nfrontier, and recent history context. `after-eval.sh` also receives the eval\nJSON and upstream ingest result. Hook stdout/stderr are capped, returned from\n`autoclanker_ingest_eval`, and recorded in `autoclanker.history.jsonl`.\nNon-zero exits and timeouts are visible but do not by themselves fail the eval\nlane.\n\nUse hooks for side effects around evidence collection: pull fresh external\ncontext before an expensive lane, append a learnings journal after an ingest,\nnotify on interesting results, or remind the agent that a lane is missing\nnotes. Do not use hooks to rewrite the fixed eval contract or hide candidate\nselection outside the frontier.\n\nFor guided setup:\n\n```bash\n/skill:autoclanker-hooks\n```\n\nThat skill ships reference scripts for frontier reminders, operator-provided\ncontext lookup, anti-thrash nudges, idea rotation, learnings journals,\nmachine-readable evidence digests, and local macOS notifications.\n\n## Start Simple\n\nYou do not need advanced Bayes JSON or a complex population file to begin. The\nsmallest useful input is still just a goal, a few rough ideas, and optional\nconstraints:\n\n```text\ngoal: lower latency without reducing quality\nrough ideas:\n- cache repeated work\n- try batch sizes 16 / 32 / 64\n- reduce allocation churn\nconstraints:\n- keep output quality stable\n- keep the eval surface fixed while comparing paths\n```\n\nThat is enough to preview beliefs and start a session. `autoclanker.beliefs.json`\ncan keep those as plain strings at first. Candidate-pool JSON, graph\ndirectives, and advanced belief authoring stay opt-in until the search actually\nneeds them. If you prefer a reusable intake file, the same beginner shape fits\nnaturally in `autoclanker.ideas.json`, but direct prompt input stays the\ndefault path.\n\n## Optimization Loop\n\n`pi-autoclanker` should feel easy to start from rough optimization ideas:\n\n```text\nrough ideas\n    ↓ preview as typed beliefs\ncandidate lanes:   [A]   [B]   [A+B]\n    ↓ evaluate available lanes in parallel when practical\neval JSON per lane\n    ↓ ingest -\u003e fit\nranked candidates + influence notes + next query\n    ↓ keep / merge / split / drop lanes\nnext era\n```\n\nThat loop is the core product:\n\n- start from rough ideas, not hand-authored Bayes syntax\n- keep isolated paths and combined paths explicit instead of burying them in\n  prompt history\n- evaluate candidates against a fixed checked-in `autoclanker.eval.sh` surface,\n  with the wrapper threading the locked upstream eval contract into that shell\n  before ingest and supporting explicit parallel lane exploration when you have\n  the workers to do it\n- keep the locked contract and frontier summary visible in `status` and\n  `export`, so trust drift and lane counts stay inspectable\n- keep the currently active objective backend, acquisition backend, and any\n  concrete lane-vs-lane follow-up query visible in the wrapper summary instead\n  of hiding them in upstream JSON\n- use `fit`, `suggest`, and `recommend-commit` to decide whether to drop,\n  merge, split, or strengthen lanes in the next era\n\nIf you already like the\n[Autoresearch](https://github.com/karpathy/autoresearch) or\n[cEvolve](https://github.com/jnormore/cevolve) intuition, the important\ndifference is that `pi-autoclanker` can run that same search loop while also\nrecording typed beliefs, explicit relations, and machine-readable uncertainty.\n\nAn evolve-style epoch still maps cleanly:\n\n```text\nEra 0 lanes: [A], [B], [C], [A+B]\n              -\u003e evaluate available lanes in parallel\n              -\u003e rank, compare, and query the interesting differences\n              -\u003e keep / merge / split / drop lanes\nEra 1 lanes: [A], [B+C], [A+B], [A+B+C], ...\n```\n\n## Why This Is Different\n\n`pi-autoclanker` should give pi users a thin, inspectable path into\n`autoclanker`:\n\n- gather rough optimization ideas from a user\n- turn them into previewable `autoclanker` sessions\n- help escalate rough ideas into advanced Bayes declarations when needed\n- structure multiple candidate pathways explicitly so `autoclanker` can rank,\n  compare, and query them\n- keep a resumable project-local session surface\n- expose thin tools and skills rather than reimplementing the Bayesian engine\n\n`pi-autoclanker` is not meant to compete with a loose planning chat on\nfree-form brainstorming alone. The value shows up when you want the exploration\nto stay structured and comparable:\n\n- rough ideas become inspectable belief batches instead of disappearing into\n  prompt history\n- candidate lanes can stay explicit instead of getting buried inside a single\n  prompt thread\n- `suggest` can evaluate an explicit candidate pool so several pathways can be\n  ranked and compared together\n- advanced beliefs can express when pathways should reinforce, combine with, or\n  stay separate from each other through explicit priors and graph directives\n- the checked-in eval shell stays fixed for the life of a session, so long\n  optimization loops cannot quietly rewrite that local eval surface mid-run\n- `fit`, `suggest`, and `recommend-commit` keep the downstream reasoning\n  machine-readable through ranked candidates, follow-up queries, backend\n  selection, and influence summaries when upstream provides them\n\nIf you want the simplest mental model, treat `pi-autoclanker` as a strict\nsuperset of an evolve-style workflow:\n\n| Evolve-style intuition | `pi-autoclanker` equivalent |\n| --- | --- |\n| idea list | rough ideas and canonical belief batch |\n| population | explicit candidate pool |\n| crossover | explicit combined candidates or positive graph links |\n| mutation | revised candidate variants or updated belief parameters |\n| fitness run | eval shell -\u003e ingest -\u003e fit |\n| rethink pass | revise beliefs, candidate lanes, or both for the next era |\n| winner | ranked candidate plus commit recommendation |\n\nWhat Bayes adds on top of that loop:\n\n- ideas can reinforce each other, conflict, or stay intentionally separate\n  through explicit priors and graph directives\n- confidence and risk can be encoded directly instead of staying implicit in\n  prompt prose\n- follow-up queries can say what evidence would most reduce uncertainty next\n- a candidate pool can emulate 1:1 evolution epochs, but the belief layer can\n  also explain why a combination should exist, not just whether it happened to\n  score well once\n\nThat is the main claim of the project: `autoclanker` should make\n[Autoresearch](https://github.com/karpathy/autoresearch) or\n[cEvolve](https://github.com/jnormore/cevolve)-style exploration easy to\nreproduce, while also making the search space more inspectable, more expressive,\nand easier to hand off honestly.\n\n## Files \u0026 output\n\nEvery session keeps five always-present core files, an optional explicit\nfrontier file, an optional project-local proposal mirror, and an optional ideas\nintake file:\n\n| File | Purpose |\n| --- | --- |\n| `autoclanker.md` | Human-readable summary of the current session state. |\n| `autoclanker.config.json` | Wrapper config, including the upstream session root. |\n| `autoclanker.beliefs.json` | Rough or advanced beliefs for the session. |\n| `autoclanker.eval.sh` | The checked-in eval surface for this session. |\n| `autoclanker.frontier.json` | Optional reviewable local frontier for multi-path runs. |\n| `autoclanker.proposals.json` | Optional project-local mirror of the active session proposal ledger once proposal state exists. |\n| `autoclanker.history.jsonl` | Local chronological wrapper log. |\n| `autoclanker.ideas.json` | Optional user-authored intake file for a goal, ideas, constraints, and simple pathway seeds. |\n| `autoclanker.hooks/` | Optional user-authored executable hooks around eval ingestion. |\n\nThose files live at the project root. They are enough for local inspection and\nlightweight handoff.\n\nA run has three layers:\n\n- `autoclanker.md`: the wrapper-local summary at the project root\n- `autoclanker.proposals.json`: the durable active-session proposal mirror when\n  proposal state exists\n- `autoclanker.history.jsonl`: the local chronological log of what the wrapper\n  did\n- `autoclanker.frontier.json`: the optional local frontier document for\n  explicit path comparison and merges\n- `autoclanker.ideas.json`: the optional user-authored intake surface that can\n  seed beliefs and, when present, a first frontier draft\n- `autoclanker.hooks/`: optional before/after eval scripts; hook output is\n  returned from ingest and logged locally\n- `.autoclanker/\u003csession\u003e/RESULTS.md` plus the session PNGs: the upstream\n  summary and visual report bundle\n- `.autoclanker/\u003csession\u003e/...`: the deeper upstream JSON and YAML artifacts when\n  you want posterior details, influence summaries, queries, or export,\n  including `observations.jsonl`, `posterior_summary.json`,\n  `influence_summary.json`, and `query.json`\n\nThat means the public story stays simple even though the underlying model is\nstronger than a plain evolve loop. You can begin from plain strings at first,\nread the summary, and only drop into the deeper artifact tree when you actually\nneed the extra structure.\n\nThe upstream session root, usually `.autoclanker/\u003csession\u003e/`, keeps the deeper\n`autoclanker` artifacts:\n\n- `RESULTS.md`\n- `observations.jsonl`\n- `posterior_summary.json`\n- `influence_summary.json`\n- `query.json`\n- `belief_graph_prior.png`\n- `belief_graph_posterior.png`\n\n`pi-autoclanker` also snapshots the checked-in `autoclanker.eval.sh` surface at\nsession start, passes the locked upstream eval contract into that shell at\ningest time, and refuses eval ingest if the local eval file drifts during the\nlife of the session.\n\n`/autoclanker status` also surfaces the wrapper-side trust and frontier state\ndirectly:\n\n- locked vs current eval-contract digest\n- eval drift status\n- last measured eval lease / stabilization summary when upstream has executed a\n  hardened eval\n- objective backend and acquisition backend from the latest upstream status and\n  suggestion artifacts\n- concrete comparison focus when upstream asks a candidate-vs-candidate or\n  family-vs-family follow-up question\n- compared lane count\n- frontier family count\n- pending queries\n- pending merge suggestions\n- the normalized Prior / Run / Posterior / Proposal briefs\n- a machine-readable dashboard model, proposal ledger mirror, evidence views,\n  and resume metadata\n\nIf you compare that with a lighter `cevolve`-style run directory:\n\n| `cevolve`-style artifact | `autoclanker` equivalent or stronger |\n| --- | --- |\n| `config.json` | `autoclanker.config.json` |\n| `ideas.json` | rough ideas plus `autoclanker.beliefs.json` |\n| `population.json` | candidate pool plus ranked candidates and posterior state |\n| `history.jsonl` | `autoclanker.history.jsonl` plus upstream `observations.jsonl` |\n| `RESULTS.md` | upstream `.autoclanker/\u003csession\u003e/RESULTS.md` plus wrapper-local `autoclanker.md` |\n| chart PNGs | upstream `convergence.png`, `candidate_rankings.png`, `belief_graph_prior.png`, and `belief_graph_posterior.png` |\n\nThe upstream session root now emits the small report bundle directly after\n`fit`, `suggest`, or `recommend-commit`, and it can be refreshed explicitly\nwith `autoclanker session render-report`. The underlying JSON and YAML\nartifacts are still there when you need the deeper Bayesian state.\n\nThe graph and report views are meant as evidence views, not as required inputs:\n\n![pi-autoclanker evidence views](docs/assets/pi-autoclanker-evidence-views.svg)\n\n- prior graph: what the session believed before evidence\n- posterior graph: what still looks plausible after evals\n- candidate rankings: which lanes look strongest right now\n- convergence: whether new evals are still changing the picture\n\n## Example demos\n\nThe shipped examples now separate the real runnable target from the wrapper-side\nsession tiers:\n\n- [`examples/targets/parser-quickstart`](examples/targets/parser-quickstart):\n  packaged parser app, benchmark harness, eval shell, and candidate pool\n- [`examples/minimal`](examples/minimal): smallest useful kickoff shape,\n  centered on direct prompt input or `autoclanker.ideas.json`, intended to be\n  used with the packaged parser target\n- [`examples/parser-demo-expanded`](examples/parser-demo-expanded): fuller\n  worked session with `autoclanker.ideas.json`, `candidates.json`,\n  `autoclanker.proposals.json`, the four-brief summary, and a checked-in eval\n  surface for that same packaged target\n\nUse `examples/targets/parser-quickstart` when you want to get your hands on a\nreal target immediately, even from a lean `autoclanker + pi-autoclanker`\ninstall. Use `examples/minimal` to see what the wrapper can start from. Use\n`examples/parser-demo-expanded` to see what the project looks like after\n`pi-autoclanker` has already written the resumable files around that target.\n\n## Developer\n\nMain deterministic gate:\n\n```bash\n./bin/dev setup\n./bin/dev check\n```\n\nHigher-confidence deterministic parity gate:\n\n```bash\n./bin/dev check-parity\n```\n\nOpt-in live gate:\n\n```bash\n./bin/dev check-live\n```\n\nSuccessful live runs record evidence under `.local/live-evidence/`.\n\nThe main contract sources are:\n\n- [`AGENTS.md`](AGENTS.md)\n- [`docs/SPEC.md`](docs/SPEC.md)\n- [`docs/DESIGN.md`](docs/DESIGN.md)\n- [`docs/COMPLIANCE_MATRIX.md`](docs/COMPLIANCE_MATRIX.md)\n- [`tests/compliance_matrix.json`](tests/compliance_matrix.json)\n- [`tests/parity_manifest.json`](tests/parity_manifest.json)\n- [`tests/python_requirement_parity.test.ts`](tests/python_requirement_parity.test.ts)\n- [`tests/python_behavior_parity.test.ts`](tests/python_behavior_parity.test.ts)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartelogan%2Fpi-autoclanker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmartelogan%2Fpi-autoclanker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartelogan%2Fpi-autoclanker/lists"}