Skip to content
Back to search

autocontext

a recursive self-improving harness designed to help your agents (and future iterations of those agents) succeed on any task

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/greyhaven-ai/autocontext with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/greyhaven-ai/autocontext'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/greyhaven-ai--autocontext/badge.svg)](/listings/greyhaven-ai--autocontext)

HTML

<a href="/listings/greyhaven-ai--autocontext"><img src="/api/listings/greyhaven-ai--autocontext/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

| Surface | Command | | ------------------- | ------------------------------------- | | Python CLI | `uv tool install autocontext==0.19.1` | | Python library/dev | `uv pip install autocontext==0.19.1` | | TypeScript/Node CLI | `bun add -g autoctx@0.19.0` | | Pi extension | `pi install npm:pi-autocontext@0.12.0` |

The PyPI package is `autocontext`; the CLI is `autoctx`. The npm package is `autoctx` (not the unrelated `autocontext` npm package). Provider variables live in [`.env.example`](.env.example). The npm CLI and TUI require Node.js 22.19.0 or newer; contributors should use the version pinned in [`ts/.nvmrc`](ts/.nvmrc).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 271 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!-- autocontext-readme-hero:start -->
  2. <p align="center">
  3. <picture>
  4. <source media="(prefers-color-scheme: dark)" srcset="autocontext/assets/autocontext-wordmark-dark.svg" />
  5. <source media="(prefers-color-scheme: light)" srcset="autocontext/assets/autocontext-wordmark.svg" />
  6. <img src="autocontext/assets/autocontext-wordmark.svg" alt="autocontext logo" width="720" style="max-width: 100%; height: auto;" />
  7. </picture>
  8. </p>
  9. <p align="center"><strong>a recursive self-improving harness designed to help your agents (and future iterations of those agents) succeed on any task</strong></p>
  10. <p align="center">
  11. <a href="https://github.com/greyhaven-ai/autocontext/blob/main/LICENSE"><img src="https://img.shields.io/github/license/greyhaven-ai/autocontext" alt="License"></a>
  12. <a href="https://github.com/greyhaven-ai/autocontext/stargazers"><img src="https://img.shields.io/github/stars/greyhaven-ai/autocontext" alt="GitHub stars"></a>
  13. <a href="https://github.com/greyhaven-ai/autocontext/commits/main"><img src="https://img.shields.io/github/last-commit/greyhaven-ai/autocontext" alt="Last commit"></a>
  14. <a href="https://pypi.org/project/autocontext/"><img src="https://img.shields.io/pypi/v/autocontext" alt="PyPI version"></a>
  15. <a href="https://www.npmjs.com/package/autoctx"><img src="https://img.shields.io/npm/v/autoctx" alt="npm version"></a>
  16. </p>
  17. <!-- autocontext-readme-hero:end -->
  18. autocontext is a harness for agent improvement. Give it a goal, it runs the task against evaluation, keeps the useful lessons, discards dead ends, and leaves traces, reports, playbooks, datasets, and optional local-model training artifacts for the next run.
  19. **Docs:** [autocontext.ai/docs](https://autocontext.ai/docs) · [quickstart](https://autocontext.ai/docs/get-started/quickstart) · [CLI reference](https://autocontext.ai/docs/cli/reference) · [changelog](https://autocontext.ai/docs/changelog)
  20. Experimental Python research: the [Qwen weight-space reproduction](examples/weight_evolution/qwen_reproduction/README.md)
  21. pins model/data/scorer assets, verifies the published checkpoint, and provides bounded paired inference with replayable reproduction reports.
  22. The [GPU acceptance workflow](examples/weight_evolution/qwen_reproduction/GPU_ACCEPTANCE.md) gates full execution; live reproduction remains pending.
  23. The [comparison-condition harness](examples/weight_evolution/qwen_comparison/README.md) exercises baseline, context, weight, combined and decoding conditions with offline synthetic fixtures.
  24. The [CPU-only editing sessions](examples/weight_evolution/qwen_sessions/README.md) create context, weight-descriptor and decoding candidates with finite durable budgets, practice-only adapter views and sealed exports into that comparison harness. Real GPU editing and benchmark practice selection remain deferred.
  25. The [adaptive editing fixtures](examples/weight_evolution/qwen_adaptive/README.md) add feedback-conditioned proposals, equal search caps, practice-based selection, and a separate confirmation gate before the final fixture audit.
  26. The [checkpoint-backed editing fixtures](examples/weight_evolution/qwen_checkpoints/README.md) apply typed edits to tiny CPU safetensors and carry independently verified input/program/output hashes through selection and confirmation. Model and GPU inference remain deferred.
  27. The [CPU inference study](examples/weight_evolution/cpu_inference/README.md) runs a pinned tiny classifier on verified checkpoint bytes and measures baseline, context, weight, combined, and decoding conditions. Its constructed tasks establish execution correctness; Qwen reproduction and GPU execution remain deferred.
  28. The [adaptive CPU search](examples/weight_evolution/cpu_adaptive/README.md) uses those measured practice scores to choose bounded context, tensor, and decoding edits, restore an earlier winner, and freeze selection before confirmation. Linux acceptance covers real memory/CPU limit failures and cleanup; GPU execution remains deferred.
  29. The [generated CPU campaign](examples/weight_evolution/cpu_campaign/README.md) compares adaptive, fixed-order, and seeded-random search at equal capacity across pinned task instances. Complete schedule accounting, read-only replay, and paired task-level reports retain failures and vetoes without treating repeated seeds as independent tasks.
  30. The [CPU search diagnostics](examples/weight_evolution/cpu_diagnostics/README.md) freeze completed selections before probing every declared single-surface option on practice cases. Separate reference costs and descriptive reports distinguish unavailable improvements, missed options, duplicate outputs, and confirmation vetoes. GPU execution remains deferred.
  31. The [controlled CPU transfer experiments](examples/weight_evolution/cpu_controls/README.md) add deterministic weight-repair, already-correct and practice-shortcut controls. A separate pinned contract preserves earlier evidence while family-specific reports test transfer under the unchanged confirmation gate. These constructed controls do not establish benchmark gains; GPU execution remains deferred.
  32. The [CPU failure supervisor](examples/weight_evolution/cpu_failures/README.md) records bounded live exception chains under a separate implementation pin. It preserves earlier journals, keeps unavailable observations unknown, and runs one declared CPU campaign with conditional practice references. GPU execution remains deferred.
  33. The [measured CPU outcomes](examples/weight_evolution/cpu_measured/README.md) add a pinned v2 failure codec, deterministic prompt redaction, and process measurements that survive errors. A small declared comparison checks native-versus-measured receipt parity without retries. Earlier evidence remains intact; GPU execution is deferred.
  34. The [measured CPU search integration](examples/weight_evolution/cpu_execution/README.md) carries those outcomes through practice, restoration, confirmation, conditional audit, and exhaustive practice references. A pinned 18-search native-versus-measured schedule checks semantic parity and preserves failed or uncertain operations and their charges. GPU execution remains deferred.
  35. The [full measured CPU pilot](examples/weight_evolution/cpu_pilot/README.md) declares 72 searches and 24 conditional practice references over the unchanged control tasks. Its CPU-only Linux/amd64 acceptance job retains complete or partial evidence, separates integrity from completion and calibration, and verifies replay without dispatch or writes. GPU execution remains deferred.
  36. The [budget-limited CPU search landscapes](examples/weight_evolution/cpu_search_landscapes/README.md) pin informative, misleading and neutral weight-search tasks with independent oracle expectations. Thirty-six equal-budget searches and twelve practice-only references measure expected wins, losses and ties, practice progress and resource usage. Context and decoding are neutral controls; the unchanged joint gate withholds audit. GPU execution remains deferred.
  37. The [CPU search robustness campaign](examples/weight_evolution/cpu_search_robustness/README.md) preserves those six tasks while varying candidate order and search budget. An exhaustive offline oracle covers 6,480 trajectories; 45 measured CPU searches and 15 practice references test order invariance, full-budget coverage and history prefixes. Variants remain nested within base tasks, and GPU execution remains deferred.
  38. The [generated CPU joint controls](examples/weight_evolution/cpu_joint_controls/README.md) pin positive, correct-baseline and practice-only repair tasks with an independent deterministic oracle. Eighteen equal-budget searches and six conditional practice references test component gains, the unchanged joint gate and actual audit routing. These constructed, seed-conditional controls do not establish adaptive superiority or benchmark gains; GPU execution remains deferred.
  39. ## Install
  40. For Python CUDA/SFT installation, follow the [maintained Accelerate build guide](docs/security/accelerate-risk-assessment.md).
  41. Published installations must install the bundled security build before adding the CUDA extra; source checkouts use the locked uv source.
  42. | Surface | Command |
  43. | ------------------- | ------------------------------------- |
  44. | Python CLI | `uv tool install autocontext==0.19.1` |
  45. | Python library/dev | `uv pip install autocontext==0.19.1` |
  46. | TypeScript/Node CLI | `bun add -g autoctx@0.19.1` |
  47. | Pi extension | `pi install npm:pi-autocontext@0.12.0` |
  48. The PyPI package is `autocontext`; the CLI is `autoctx`. The npm package is `autoctx` (not the unrelated `autocontext` npm package). Provider variables live in [`.env.example`](.env.example).
  49. The npm CLI and TUI require Node.js 22.19.0 or newer; contributors should use
  50. the version pinned in [`ts/.nvmrc`](ts/.nvmrc).
  51. ## 30-Second Run
  52. Pi is the lowest-friction provider because it uses your local agent auth:
  53. ```bash
  54. AUTOCONTEXT_AGENT_PROVIDER=pi \
  55. AUTOCONTEXT_PI_COMMAND=pi \
  56. autoctx solve "improve customer-support replies for billing disputes" --iterations 3
  57. ```
  58. Use `AUTOCONTEXT_AGENT_PROVIDER=anthropic`, `openai-compatible`, `openrouter`, `claude-cli`, `codex`, `pi-rpc`, or another provider when you need that runtime. See [agent integration](autocontext/docs/agent-integration.md) for the full matrix.
  59. Running it on your own GPU instead? [Self-hosted models](autocontext/docs/self-hosted-models.md) covers the whole loop on vLLM, Ollama, or any OpenAI-compatible endpoint — including what each role actually resolves to, and why constrained output matters more on open weights.
  60. Self-hosted endpoints can additionally declare `AUTOCONTEXT_PROVIDER_HOSTING=local` and a `fast`, `mid_tier`, or `frontier` `AUTOCONTEXT_PROVIDER_CAPABILITY`; role-specific endpoints use matching `<ROLE>_PROVIDER_*` declarations.
  61. Prime remote execution also supports opt-in accelerator requests with explicit
  62. type/count, immutable-image, region, and telemetry capability validation. It
  63. fails before provider creation when the configured pool cannot satisfy the
  64. request and never downgrades accelerator work to CPU; see
  65. [remote execution sessions](docs/remote-execution-sessions.md).
  66. Shipped Prime generation and campaign paths persist a durable pre-dispatch
  67. claim plus the complete result/ledger projection before returning paid work;
  68. restart never treats an unresolved or already committed request as permission
  69. to provision another sandbox.
  70. ## Agent Entry Points
  71. - **Pi:** install `pi-autocontext`, then ask Pi to solve, judge, improve, list, or inspect runs through the packaged skill.
  72. - **MCP clients:** run `autoctx serve mcp` or `bunx autoctx serve mcp` and expose the tools to Claude Code, Cursor, or another MCP client.
  73. - **Hermes:** export the CLI-first skill with `uv run autoctx hermes export-skill --with-references --json`.
  74. Full setup: [autocontext/docs/agent-integration.md](autocontext/docs/agent-integration.md).
  75. ## What A Run Leaves Behind
  76. ```text
  77. runs/<run_id>/
  78. ├── trace.jsonl
  79. ├── generations/<n>/{strategy.json,analysis.md,score.json}
  80. ├── report.md
  81. └── artifacts/
  82. knowledge/<scenario>/
  83. ├── playbook.md
  84. ├── hints.md
  85. ├── tools/
  86. └── context_bundles/{bundles,candidates,promotions,active.json}
  87. ```
  88. Everything is filesystem-first: inspect it, diff it, replay it, export it, or feed it into training.
  89. Kernel campaigns extend that contract with exact provider-generation receipts,
  90. bounded paid-call accounting, content-addressed lineage, and safe stop/status/resume.
  91. Coach and architect context changes are stored as immutable candidates and are
  92. not served until matched candidate/incumbent trials confirm them. The live
  93. serving boundary can additionally require a cancellable independent audit and
  94. a durable campaign-wide false-promotion budget; exact causal credit is accepted
  95. only from verified single-component manifest additions. See
  96. [context bundles and outcome-gated promotion](docs/context-bundles.md).
  97. Python also provides an opt-in [executable-skill bridge](autocontext/docs/executable-skills.md)
  98. for verified schema-migration proposals in Docker, with explicit eligibility
  99. and promotion-gated serving.
  100. An opt-in [skill/model router](autocontext/docs/skill-routing.md) adds verified
  101. fallback and explicit abstention under one request budget.
  102. The [schema-migration reuse study](autocontext/benchmarks/skill_reuse/README.md)
  103. compares baseline, textual context, executable reuse and cheaper-model controls
  104. under frozen paired evaluation; fixture runs are infrastructure evidence only.
  105. Controlled component trials feed
  106. [ablation-backed attribution](docs/context-attribution.md), so prompt selection
  107. can demote low-value context without presenting edit-size correlation as causal.
  108. Python kernel evolution can also compose bounded studies across variable-shape
  109. matmul, fused elementwise/reduction, and causal-attention families. Each family
  110. retains independent primary/confirmation evidence and per-case floors;
  111. cross-shape, cross-hardware, and cross-family trials distinguish portable,
  112. partially transferring, specialist, and plateau outcomes without an aggregate
  113. score hiding a failed workload. See the
  114. [kernel evolution guide](autocontext/docs/kernel-evolution.md#multi-workload-studies).
  115. ## Core Surfaces
  116. | Surface | Command | Use it for |
  117. | ------------- | ------------------------------------------------------- | ------------------------------------------------------- |
  118. | `solve` | `autoctx solve "..." --iterations 3` | Start from a plain-language goal |
  119. | `run` | `autoctx run <scenario> --iterations 3` | Improve a saved scenario |
  120. | `status` | `autoctx status <run-id> --json` | Read one run snapshot |
  121. | `watch` | `autoctx watch <run-id> --ndjson` | Stream run snapshots |
  122. | `show` | `autoctx show <run-id> --best --json` | Inspect a selected generation |
  123. | `simulate` | `autoctx simulate -d "..."` | Model/replay/compare system behavior |
  124. | `investigate` | `autoctx investigate -d "..."` | Evidence-driven diagnosis |
  125. | `scenario` | `autoctx scenario create --help` | Create from a description, template, or harness spec |
  126. | `mission` | `autoctx mission create --name "..." --goal "..."` | Verifier-driven multi-step goals |
  127. | `train` | `uv run autoctx train --scenario <name> --data <jsonl>` | Distill stable behavior into a cheaper runtime (Python) |
  128. | `serve mcp` | `autoctx serve mcp` | Give an agent the autocontext tool surface |
  129. | `tui` | `autoctx tui [--connect <server>]` | Operate or attach to a run from the pi-tui terminal UI |
  130. Running bare `autoctx` shows the concise paved-road workflow. Use `autoctx
  131. --help --all` in the npm CLI or `autoctx commands --all` in the Python CLI for
  132. the full catalog. `--iterations` is the primary iteration flag; `--gens` is a
  133. compatibility alias. `autoctx --version --json` reports the package version and
  134. runtime (`python` or `typescript`).
  135. Python owns the full control-plane package; TypeScript owns several operator-facing surfaces, the TUI, and Node runtime adapters. Start with [autocontext/README.md](autocontext/README.md) or [ts/README.md](ts/README.md).
  136. HTTP and WebSocket control planes bind to loopback by default. A non-loopback
  137. bind fails closed unless `AUTOCONTEXT_SERVER_TOKEN` contains a random value of
  138. at least 32 characters. Send it as an `Authorization: Bearer` value; browser
  139. WebSocket clients use the `autocontext.bearer.<base64url-token>` subprotocol.
  140. Tokens in endpoint URLs are rejected. See the
  141. [persistent-host security model](autocontext/docs/persistent-host.md#trust-and-credential-boundary)
  142. before exposing a server beyond one trusted operator.
  143. <!-- autocontext-whats-new:start -->
  144. ## What's New in 0.19.0
  145. - **Safer run re-entry:** autoctx resume continues a run with its stored scenario and target, completed runs stay unchanged, and re-entering under a different provider or executor mode is refused unless resume gets --allow-runtime-change. Agent-task runs, A/B tests and TypeScript runs refuse run ids that already exist.
  146. - **Reliable shared databases:** several processes can start against one new SQLite database without migration-ledger or WAL lock failures, and cross-runtime migrations keep runs.minimum_generations, re-adding it where an earlier migration dropped it.
  147. - **Correct artifact paths:** Python run artifacts no longer land at doubled paths under relative artifact roots, and artifact_write hooks in either runtime cannot redirect a write out of its managed root through a symlink.
  148. - **Opt-in executable skills (Python):** for a schema-migration pilot, context bundles can carry Docker-isolated executable skills routed with verified model fallback, and a complete routed policy is promoted only through a fail-closed quality and cost gate. Nothing is enabled automatically.
  149. - **Evaluator provenance and human labels (Python):** judge epochs bind an immutable serving specification that includes calibration examples, and autoctx labels collects human-only judge labels with random audits and protected holdout splits.
  150. - **Measured reuse studies:** archived GridCTF policy-reuse and schema-migration reuse studies report quality, fallback and resource costs. GridCTF dollar costs are unknown, the schema-migration study records model-credit charges but not full lifecycle cost, and neither study authorizes production promotion.
  151. <!-- autocontext-whats-new:end -->
  152. ### npm 0.17.3 minimum iteration floors
  153. `autoctx@0.17.3` advertises `minimum_iterations_v1`. Structured task contracts
  154. may set `minimumIterations`, interactive `start_run` commands may override it
  155. with `minimum_generations`, and the effective value must be between one and the
  156. maximum iteration count. Normal quality, plateau, unchanged-output, and cached
  157. verdict convergence cannot stop below the floor; cancellation, provider or
  158. evaluator failure, and time/token safety exits remain immediate. The effective
  159. minimum is retained in live protocol metadata and SQLite-backed run history so
  160. Cockpit clients recover it after restart.
  161. ### npm 0.17.2 structured tasks and durable outcomes
  162. `autoctx@0.17.2` is a TypeScript-only patch release; the Python package remains
  163. at `autocontext==0.17.0`. The npm package adds:
  164. - **Structured desktop missions:** protocol-v2 servers advertise
  165. `structured_task_creation_v1` and accept strict, versioned `create_task`
  166. commands with bounded source contents, explicit data roles, retained
  167. provenance, integrity checks, ordered setup/run progress, and durable
  168. multi-round results.
  169. - **Privacy-preserving evaluation:** evaluator-only sources can affect scores
  170. without entering candidate prompts, revision feedback, transcripts, or
  171. retained analyst output.
  172. - **Bounded artifact continuation:** truncated initial or revised task outputs
  173. can continue within explicit segment and total-size limits; exhausted or
  174. non-growing continuation fails closed before evaluation.
  175. - **Durable task outcomes:** completed saved agent tasks advertise
  176. `agent_task_outcome_v1`, retain a compact terminal receipt and per-generation
  177. evaluator evidence, and expose the complete versioned outcome through
  178. SQLite-backed Cockpit inspection.
  179. The package also carries the TypeScript-first runtime work introduced in 0.16.0
  180. and hardened in 0.16.1:
  181. - **Host-owned live composition:** typed runtime capabilities, scoped cleanup
  182. and effect policies, reactive component graphs, and durable transactional
  183. activation/rollback for trusted hosts.
  184. - **A production-oriented operator TUI:** the pi-tui client supports local and
  185. remote attachment, durable replay, run control and inspection, and bounded,
  186. redacted terminal state on Node.js 22.19+.
  187. - **Image-aware interactive sessions:** compatible TypeScript providers can
  188. advertise `image_attachments_v1`; attachment validation is bounded and
  189. fail-closed before provider inference.
  190. - **Protocol and terminal hardening:** exact capability negotiation, protected
  191. priority controls, bounded WebSocket resources, credential redaction, and
  192. terminal-control sanitization are enforced across the interactive path.
  193. Python parity for structured task creation and outcomes, the pi-tui client, and
  194. image attachments remains deferred.
  195. See the [TypeScript guide](ts/README.md), [runtime composition
  196. contracts](docs/internal/runtime-component-graph.md), and the full
  197. [changelog](CHANGELOG.md) for details.
  198. ## Scenario Families
  199. The shipped families cover games, agent tasks, simulations, artifact editing, investigations, workflows, negotiation, schema evolution, tool fragility, operator loops, and coordination. Python and TypeScript share the family vocabulary; see [docs/internal/scenario-parity-matrix.md](docs/internal/scenario-parity-matrix.md) for parity details.
  200. ## Package Guides
  201. | Need | Go here |
  202. | --------------------------------------------- | ---------------------------------------------- |
  203. | Python CLI/library, MCP, HTTP, training | [autocontext/README.md](autocontext/README.md) |
  204. | Node CLI, TUI, missions, Fetch/agent adapters | [ts/README.md](ts/README.md) |
  205. | Pi package | [pi/README.md](pi/README.md) |
  206. | Copy-paste examples | [examples/README.md](examples/README.md) |
  207. | Concepts and docs index | [docs/README.md](docs/README.md) |
  208. | Contributor setup | [CONTRIBUTING.md](CONTRIBUTING.md) |
  209. | Repo guide for agents | [AGENTS.md](AGENTS.md) |
  210. ## Project Signals
  211. [![npm downloads](https://img.shields.io/npm/dm/autoctx?logo=npm&label=npm%20downloads)](https://www.npmjs.com/package/autoctx)
  212. [![PyPI downloads](https://img.shields.io/pypi/dm/autocontext?logo=pypi&label=PyPI%20downloads)](https://pypi.org/project/autocontext/)
  213. ## Acknowledgments
  214. Thanks to [George](https://github.com/GeorgeH87) for generously donating the `autocontext` name on PyPI.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.