agentleFS
alexnodelandalexnodeland/hoist/AGENTS.md

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.

  • In this repository5 other files it gives its agents.

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
  1. Distinctive:

    Honest reports: Every metric in a report gets a definition in the "Reading the numbers" section.

    line 33

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 cut

Conventions

  • 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 rustdoc

make help lists the other targets, among them make bless after a change to a command or an option (it regenerates docs/cli.md).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.