hoist
AGENTS.md2 starsChanged 33 days agoMITView on GitHub
Hoist learns, from an LLM agent's recorded tool calls, which reads it makes next and where their arguments come from, and serves those reads through an MCP proxy in the same tool result, so the agent needs fewer LLM turns (tagline: Read ahead of your agent.). A flow only reads. Its lookups are decided by counting (the reach decider, with no model), by a learned habit, or by an arbiter that also asks a System-One model (TypeSafe's Jev). Where no…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
The file
We split this AGENTS.md into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 33
Honest reports: Every metric in a report gets a definition in the "Reading the numbers" section.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent context: Hoist
Hoist learns, from an LLM agent's recorded tool calls, which reads it makes next and where their arguments come from, and serves those reads through an MCP proxy in the same tool result, so the agent needs fewer LLM turns (tagline: Read ahead of your agent.). A flow only reads. Its lookups are decided by counting (the reach decider, with no model), by a learned habit, or by an arbiter that also asks a System-One model (TypeSafe's Jev). Where no user speaks, hoist-procedure runs a workflow compiled once from traces. The design is RFC-001 (docs/rfc/001-habit-compiler.md); the decisions are summarized in docs/design.md; the paper is paper/hoist.md. Brand words and numbers follow brand/messaging.md: every number comes from docs/results/claims.md or the paper, with its scope.
Layout
crates/
hoist-trace/ episode schema, τ²-bench and MCP proxy log ingest, tool manifests
hoist-model/ abstraction, back-off world model, α posterior (fugue), provenance, runs, policy
hoist-oracle/ Oracle trait, Jev client (feature "http"), replay cache, mock
hoist-report/ `hoist` CLI: first run (`init`, `doctor`, `completions`); the Phase 0 report; Phase 0b (`shadow`: System-One questions at held-out decisions; `arbitrate`: combining them with the habit); read-only flows (`flow`: compile, learn, serve); policy guards (`guards`); the flow audit as a fugue program (`audit`)
hoist-mcp/ stdio MCP proxy: records sessions, and in active mode (`active`) runs a flow, guards, `hoist_commit` and the conversation context; plus `hoist-procedure`, the procedure runtime, and a demo MCP server (echo or a tiny retail world)
hoist-console/ the console's server (`hoist-console`, axum): a JSON API over ~/.hoist (sessions, flows, the server registry `servers.json`, jobs that run the `hoist` CLI), token auth, and the UI embedded; its tests run over `tests/fixtures/home`
console/ the console's UI (Vue); `src/api/generated/` is the API's TypeScript, which `make types` writes
pilot/ live τ²-bench episodes: GLM in Claude Code, tools over MCP, the flows arm, and a replay check
pilot/bench/ live runs of other benchmarks (AgentDojo, BFCL) in their own environments
website/ the documentation site (VitePress), deployed to GitHub Pages by .github/workflows/pages.yml
site/ the research notebook of the rounds through 2026-09-25, served by the site at /notebook/
paper/ the working paper, paper/hoist.md
brand/ the brand kit: logo, tokens, messaging, the explainer and the videos
docs/
design.md decisions, architecture and implementation status
results/ dated results with interpretation
install.md every way to install; releasing.md, how a release is cutConventions
- One schema. Everything downstream reads
hoist_trace::Episode, never a benchmark's native format. Add new sources as ingest modules. - Posteriors, not frequencies. Anything that drives a decision is a posterior predictive, with evidence counts next to it. Use closed forms where they exist, and fugue where they do not.
- Replay by default. Oracle calls go through
ReplayCache, so experiments pay for each distinct question once and re-run for free. Never commit cache contents that contain third-party data. - Honest reports. Every metric in a report gets a definition in the "Reading the numbers" section. A proxy must say it is a proxy.
- Secrets. Keys come from the environment (
TYPESAFE_API_KEY,ZAI_API_KEY, and later MiniMax's). Never log or commit them. The Z.ai key is a coding-plan key: use it only through Claude Code (pilot/glm-claude.sh), and keep runs small.
Before committing
make fmt # cargo fmt --all
make ci # what CI's check job runs: the formatting check, clippy, the tests and doctests, and rustdocmake help lists the other targets, among them make bless after a change to a command or an option (it regenerates docs/cli.md).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

