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.
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
Markdown
[](/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
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.
- <!-- autocontext-readme-hero:start -->
- <p align="center">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="autocontext/assets/autocontext-wordmark-dark.svg" />
- <source media="(prefers-color-scheme: light)" srcset="autocontext/assets/autocontext-wordmark.svg" />
- <img src="autocontext/assets/autocontext-wordmark.svg" alt="autocontext logo" width="720" style="max-width: 100%; height: auto;" />
- </picture>
- </p>
- <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>
- <p align="center">
- <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>
- <a href="https://github.com/greyhaven-ai/autocontext/stargazers"><img src="https://img.shields.io/github/stars/greyhaven-ai/autocontext" alt="GitHub stars"></a>
- <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>
- <a href="https://pypi.org/project/autocontext/"><img src="https://img.shields.io/pypi/v/autocontext" alt="PyPI version"></a>
- <a href="https://www.npmjs.com/package/autoctx"><img src="https://img.shields.io/npm/v/autoctx" alt="npm version"></a>
- </p>
- <!-- autocontext-readme-hero:end -->
- 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.
- **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)
- Experimental Python research: the [Qwen weight-space reproduction](examples/weight_evolution/qwen_reproduction/README.md)
- pins model/data/scorer assets, verifies the published checkpoint, and provides bounded paired inference with replayable reproduction reports.
- The [GPU acceptance workflow](examples/weight_evolution/qwen_reproduction/GPU_ACCEPTANCE.md) gates full execution; live reproduction remains pending.
- The [comparison-condition harness](examples/weight_evolution/qwen_comparison/README.md) exercises baseline, context, weight, combined and decoding conditions with offline synthetic fixtures.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- ## Install
- For Python CUDA/SFT installation, follow the [maintained Accelerate build guide](docs/security/accelerate-risk-assessment.md).
- Published installations must install the bundled security build before adding the CUDA extra; source checkouts use the locked uv source.
- | 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.1` |
- | 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).
- ## 30-Second Run
- Pi is the lowest-friction provider because it uses your local agent auth:
- ```bash
- AUTOCONTEXT_AGENT_PROVIDER=pi \
- AUTOCONTEXT_PI_COMMAND=pi \
- autoctx solve "improve customer-support replies for billing disputes" --iterations 3
- ```
- 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.
- 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.
- 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.
- Prime remote execution also supports opt-in accelerator requests with explicit
- type/count, immutable-image, region, and telemetry capability validation. It
- fails before provider creation when the configured pool cannot satisfy the
- request and never downgrades accelerator work to CPU; see
- [remote execution sessions](docs/remote-execution-sessions.md).
- Shipped Prime generation and campaign paths persist a durable pre-dispatch
- claim plus the complete result/ledger projection before returning paid work;
- restart never treats an unresolved or already committed request as permission
- to provision another sandbox.
- ## Agent Entry Points
- - **Pi:** install `pi-autocontext`, then ask Pi to solve, judge, improve, list, or inspect runs through the packaged skill.
- - **MCP clients:** run `autoctx serve mcp` or `bunx autoctx serve mcp` and expose the tools to Claude Code, Cursor, or another MCP client.
- - **Hermes:** export the CLI-first skill with `uv run autoctx hermes export-skill --with-references --json`.
- Full setup: [autocontext/docs/agent-integration.md](autocontext/docs/agent-integration.md).
- ## What A Run Leaves Behind
- ```text
- runs/<run_id>/
- ├── trace.jsonl
- ├── generations/<n>/{strategy.json,analysis.md,score.json}
- ├── report.md
- └── artifacts/
- knowledge/<scenario>/
- ├── playbook.md
- ├── hints.md
- ├── tools/
- └── context_bundles/{bundles,candidates,promotions,active.json}
- ```
- Everything is filesystem-first: inspect it, diff it, replay it, export it, or feed it into training.
- Kernel campaigns extend that contract with exact provider-generation receipts,
- bounded paid-call accounting, content-addressed lineage, and safe stop/status/resume.
- Coach and architect context changes are stored as immutable candidates and are
- not served until matched candidate/incumbent trials confirm them. The live
- serving boundary can additionally require a cancellable independent audit and
- a durable campaign-wide false-promotion budget; exact causal credit is accepted
- only from verified single-component manifest additions. See
- [context bundles and outcome-gated promotion](docs/context-bundles.md).
- Python also provides an opt-in [executable-skill bridge](autocontext/docs/executable-skills.md)
- for verified schema-migration proposals in Docker, with explicit eligibility
- and promotion-gated serving.
- An opt-in [skill/model router](autocontext/docs/skill-routing.md) adds verified
- fallback and explicit abstention under one request budget.
- The [schema-migration reuse study](autocontext/benchmarks/skill_reuse/README.md)
- compares baseline, textual context, executable reuse and cheaper-model controls
- under frozen paired evaluation; fixture runs are infrastructure evidence only.
- Controlled component trials feed
- [ablation-backed attribution](docs/context-attribution.md), so prompt selection
- can demote low-value context without presenting edit-size correlation as causal.
- Python kernel evolution can also compose bounded studies across variable-shape
- matmul, fused elementwise/reduction, and causal-attention families. Each family
- retains independent primary/confirmation evidence and per-case floors;
- cross-shape, cross-hardware, and cross-family trials distinguish portable,
- partially transferring, specialist, and plateau outcomes without an aggregate
- score hiding a failed workload. See the
- [kernel evolution guide](autocontext/docs/kernel-evolution.md#multi-workload-studies).
- ## Core Surfaces
- | Surface | Command | Use it for |
- | ------------- | ------------------------------------------------------- | ------------------------------------------------------- |
- | `solve` | `autoctx solve "..." --iterations 3` | Start from a plain-language goal |
- | `run` | `autoctx run <scenario> --iterations 3` | Improve a saved scenario |
- | `status` | `autoctx status <run-id> --json` | Read one run snapshot |
- | `watch` | `autoctx watch <run-id> --ndjson` | Stream run snapshots |
- | `show` | `autoctx show <run-id> --best --json` | Inspect a selected generation |
- | `simulate` | `autoctx simulate -d "..."` | Model/replay/compare system behavior |
- | `investigate` | `autoctx investigate -d "..."` | Evidence-driven diagnosis |
- | `scenario` | `autoctx scenario create --help` | Create from a description, template, or harness spec |
- | `mission` | `autoctx mission create --name "..." --goal "..."` | Verifier-driven multi-step goals |
- | `train` | `uv run autoctx train --scenario <name> --data <jsonl>` | Distill stable behavior into a cheaper runtime (Python) |
- | `serve mcp` | `autoctx serve mcp` | Give an agent the autocontext tool surface |
- | `tui` | `autoctx tui [--connect <server>]` | Operate or attach to a run from the pi-tui terminal UI |
- Running bare `autoctx` shows the concise paved-road workflow. Use `autoctx
- --help --all` in the npm CLI or `autoctx commands --all` in the Python CLI for
- the full catalog. `--iterations` is the primary iteration flag; `--gens` is a
- compatibility alias. `autoctx --version --json` reports the package version and
- runtime (`python` or `typescript`).
- 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).
- HTTP and WebSocket control planes bind to loopback by default. A non-loopback
- bind fails closed unless `AUTOCONTEXT_SERVER_TOKEN` contains a random value of
- at least 32 characters. Send it as an `Authorization: Bearer` value; browser
- WebSocket clients use the `autocontext.bearer.<base64url-token>` subprotocol.
- Tokens in endpoint URLs are rejected. See the
- [persistent-host security model](autocontext/docs/persistent-host.md#trust-and-credential-boundary)
- before exposing a server beyond one trusted operator.
- <!-- autocontext-whats-new:start -->
- ## What's New in 0.19.0
- - **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.
- - **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.
- - **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.
- - **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.
- - **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.
- - **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.
- <!-- autocontext-whats-new:end -->
- ### npm 0.17.3 minimum iteration floors
- `autoctx@0.17.3` advertises `minimum_iterations_v1`. Structured task contracts
- may set `minimumIterations`, interactive `start_run` commands may override it
- with `minimum_generations`, and the effective value must be between one and the
- maximum iteration count. Normal quality, plateau, unchanged-output, and cached
- verdict convergence cannot stop below the floor; cancellation, provider or
- evaluator failure, and time/token safety exits remain immediate. The effective
- minimum is retained in live protocol metadata and SQLite-backed run history so
- Cockpit clients recover it after restart.
- ### npm 0.17.2 structured tasks and durable outcomes
- `autoctx@0.17.2` is a TypeScript-only patch release; the Python package remains
- at `autocontext==0.17.0`. The npm package adds:
- - **Structured desktop missions:** protocol-v2 servers advertise
- `structured_task_creation_v1` and accept strict, versioned `create_task`
- commands with bounded source contents, explicit data roles, retained
- provenance, integrity checks, ordered setup/run progress, and durable
- multi-round results.
- - **Privacy-preserving evaluation:** evaluator-only sources can affect scores
- without entering candidate prompts, revision feedback, transcripts, or
- retained analyst output.
- - **Bounded artifact continuation:** truncated initial or revised task outputs
- can continue within explicit segment and total-size limits; exhausted or
- non-growing continuation fails closed before evaluation.
- - **Durable task outcomes:** completed saved agent tasks advertise
- `agent_task_outcome_v1`, retain a compact terminal receipt and per-generation
- evaluator evidence, and expose the complete versioned outcome through
- SQLite-backed Cockpit inspection.
- The package also carries the TypeScript-first runtime work introduced in 0.16.0
- and hardened in 0.16.1:
- - **Host-owned live composition:** typed runtime capabilities, scoped cleanup
- and effect policies, reactive component graphs, and durable transactional
- activation/rollback for trusted hosts.
- - **A production-oriented operator TUI:** the pi-tui client supports local and
- remote attachment, durable replay, run control and inspection, and bounded,
- redacted terminal state on Node.js 22.19+.
- - **Image-aware interactive sessions:** compatible TypeScript providers can
- advertise `image_attachments_v1`; attachment validation is bounded and
- fail-closed before provider inference.
- - **Protocol and terminal hardening:** exact capability negotiation, protected
- priority controls, bounded WebSocket resources, credential redaction, and
- terminal-control sanitization are enforced across the interactive path.
- Python parity for structured task creation and outcomes, the pi-tui client, and
- image attachments remains deferred.
- See the [TypeScript guide](ts/README.md), [runtime composition
- contracts](docs/internal/runtime-component-graph.md), and the full
- [changelog](CHANGELOG.md) for details.
- ## Scenario Families
- 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.
- ## Package Guides
- | Need | Go here |
- | --------------------------------------------- | ---------------------------------------------- |
- | Python CLI/library, MCP, HTTP, training | [autocontext/README.md](autocontext/README.md) |
- | Node CLI, TUI, missions, Fetch/agent adapters | [ts/README.md](ts/README.md) |
- | Pi package | [pi/README.md](pi/README.md) |
- | Copy-paste examples | [examples/README.md](examples/README.md) |
- | Concepts and docs index | [docs/README.md](docs/README.md) |
- | Contributor setup | [CONTRIBUTING.md](CONTRIBUTING.md) |
- | Repo guide for agents | [AGENTS.md](AGENTS.md) |
- ## Project Signals
- [](https://www.npmjs.com/package/autoctx)
- [](https://pypi.org/project/autocontext/)
- ## Acknowledgments
- 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 inFree to use. If it’s helped, pass it on.