hoist
CLAUDE.md2 starsChanged 33 days agoMITView on GitHub
AGENTS.md, imported above, is the project context every coding agent shares: what Hoist is, the layout, the conventions, and the rules on secrets. This file adds what Claude Code needs on top of it. Keep project facts in AGENTS.md and Claude Code specifics here. make help lists every target. The Rust targets run the same commands as CI. One test: cargo test -p hoist-report --test formats, or cargo test -p hoist-model <name>. In several git worktrees at once, give each…
- Reads credentials
The file
We split this CLAUDE.md into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 52
When a result changes, change the ledger and every page that quotes it in the same commit.
- Very specific: line 68
Run make ci. Add make quickstart and make walkthrough when the proxy or the CLI changed, make ui-check and make e2e when console/ or the …
- Very specific: line 69
Update what the change touches: docs/cli.md (make bless), docs/formats.md, the guide in website/, and CHANGELOG.md under *Unreleased*.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.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
CLAUDE.md
@AGENTS.md
AGENTS.md, imported above, is the project context every coding agent shares: what Hoist is, the layout, the conventions, and the rules on secrets. This file adds what Claude Code needs on top of it. Keep project facts in AGENTS.md and Claude Code specifics here.
Everyday commands
make help lists every target. The Rust targets run the same commands as CI.
| Command | What it runs |
make fmt | cargo fmt --all |
make check | cargo fmt --all -- --check |
make lint | cargo clippy --all-targets -- -D warnings, and again on the console's ts feature |
make test | cargo test --all-targets, then cargo test --doc |
make types | Rewrites the API's TypeScript for the UI (console/src/api/generated/), and fails if it was out of date |
make doc | cargo doc --no-deps, with rustdoc warnings as errors |
make ci | check, lint, test, types and doc: CI's check job. Run it before every push |
make msrv | cargo check on Rust 1.88, Cargo.toml's rust-version, with the lockfile |
make coverage | cargo-llvm-cov: writes lcov.info; fails under COVERAGE_MIN in the Makefile, or when a line the branch adds is not run by any test (scripts/patch_coverage.py, against origin/main: fetch it first) |
make bless | HOIST_BLESS=1 cargo test: regenerates docs/cli.md and docs/review.md's examples |
make quickstart, make walkthrough | the quickstart and the walkthrough, as CI's walkthrough job runs them, on a debug build |
make site | the documentation site, which fails on a dead link |
make ui-check, make e2e | the console's UI (console/): formatting, lint, types, unit tests and build; then the end-to-end tests, as CI's ui job runs them |
make console | builds the UI and runs the console on ~/.hoist (ARGS="--read-only") |
One test: cargo test -p hoist-report --test formats, or cargo test -p hoist-model <name>.
In several git worktrees at once, give each its own target directory (the default, target/ in the worktree). Cargo names the workspace's artifacts the same whatever the checkout, and judges them fresh by the files they were last built from, so one CARGO_TARGET_DIR shared between worktrees can run another worktree's code. If you must share one, run cargo clean -p hoist-console -p hoist-report -p hoist-mcp -p hoist-trace -p hoist-model -p hoist-oracle before building in the other worktree.
A hook runs rustfmt on every .rs file you edit or write (.claude/hooks/format-rust.sh), so you need not format by hand. make check still checks it.
The docs are tested against the code, so a change to the CLI or a file format fails the tests until the docs follow:
docs/cli.mdis generated from the clap definitions, and a test in each binary fails when its section is stale. After changing a command or an option, runmake blessand commit the result.crates/hoist-report/tests/formats.rsfails whendocs/formats.mddoes not name a field a flow or an arbiter file holds, and checksdocs/review.md's examples.- CI runs
docs/walkthrough.md(scripts/walkthrough.py) andexamples/quickstart/run.sh, so neither can drift from the code.
Running it
- The quickstart:
make quickstart. It records six sessions onhoist-mcp-demo's shop, then learns, reviews and serves a flow, with no key and no network. - The walkthrough:
make walkthroughrunsdocs/walkthrough.mdon the official MCP filesystem server, whichnpxfetches, so it needs Node and the network. - The console:
make console, or with the UI's dev server and hot reload:cargo run -p hoist-console -- --no-authin one terminal andnpm --prefix console run devin another (it proxies/apito 127.0.0.1:7878).npm --prefix console run dev:mockneeds no server: it answers fromconsole/mock/. - The CLI:
cargo run -p hoist-report -- <command>runshoist;cargo run -p hoist-mcp --bin hoist-mcp -- <args>runs the proxy.hoist doctorchecks an install.
Results, claims and numbers
- Each round of experiments has a dated page in
docs/results/(<topic>-YYYY-MM-DD.md), with its rows (.json), answer bundles and episode archives beside it.docs/results/README.mdindexes the pages by date. - The claims ledger,
docs/results/claims.md, lists each headline number with its kind of evidence (live, replay or record), its interval, and the script that recomputes it. The paper ispaper/hoist.md. RFC-001 (docs/rfc/001-habit-compiler.md) records what each round changed, one amendment per round. - Every number you write comes from
docs/results/claims.mdor the paper, with its scope: the model, the benchmark, live or replayed, and the interval. Copy it as the ledger writes it: 27.9% is not "almost 30%". Never estimate, round up or generalize past the scope. If no page has the number, say so rather than supply one. - When a result changes, change the ledger and every page that quotes it in the same commit. The
resultsskill has the list.
Writing style
Calm and exact, as brand/messaging.md sets out: say what a thing does and how you know, in short sentences. No hype words, no unscoped claims, and no model names as endorsements. Hoist is always capitalised in prose; commands, crates, paths and environment variables stay lowercase or upper-case as written (hoist, hoist-mcp, HOIST_HOME). Use the project's terms: LLM turns, reads or lookups, a flow, a detour, the reach decider; live, replay, record. Commit messages follow git log: a subject that says what changed, in plain words with no type prefix, and a body in the same prose, with a list when there are several parts.
Never
- Commit, print or log a secret. Keys come from the environment (
TYPESAFE_API_KEY,ZAI_API_KEY). Check one only with[ -n "$TYPESAFE_API_KEY" ]; never echo it or write it to a file..claude/settings.jsondenies Claude reads of.envfiles, key files under~/.hoist, the pilot's key files and credential stores. - Spend Z.ai or Jev credit casually. The live pilots (
pilot/run_*.py,pilot/bench/run_bench_*.py,pilot/glm-claude.sh,pilot/claude-agent.sh) and any command with--oracle jevorjev-checkspend money or a plan's quota. Run them only when the owner asks, keep runs small, and prefer the replay cache and the published answer bundles. The Z.ai key is a coding-plan key, used only through Claude Code (pilot/glm-claude.sh). The settings ask before each of these. - Commit session logs, transcripts or caches. Recorded sessions (
~/.hoist/logs),pilot/runs/, Claude Code transcripts,.oracle-cache/and answer caches holding third-party data stay out of git. Episodes are published only in a results page's archive, and only from benchmark environments, whose customers are synthetic; a real user's sessions are shared only throughhoist redact(docs/privacy.md). - Push to main, force-push, tag or publish (
cargo publish,gh release) unless the owner says to. Only empty 0.0.0 placeholders are published to crates.io.
Pull requests
- Branch from
main, one purpose per branch:git switch -c <topic> origin/main. - Run
make ci. Addmake quickstartandmake walkthroughwhen the proxy or the CLI changed,make ui-checkandmake e2ewhenconsole/or the console's API changed, andmake sitewhenwebsite/,docs/orpaper/changed: the Pages build runs only after merging. - Update what the change touches:
docs/cli.md(make bless),docs/formats.md, the guide inwebsite/, andCHANGELOG.mdunder Unreleased. - Open the PR with
.github/pull_request_template.md: what changes and why, how it was checked, and the checklist. - CI must be green before merging: ci.yml (check, ui, MSRV, walkthrough, the macOS and Windows builds) and Coverage, and container.yml when the image's inputs change. The
stewardskill has what each job checks and how to fix it.
Skills and agents in this repository
check: run what CI runs before a push, and read its failures.results: write up an experiment, updating the results page, the index, the ledger, the paper and RFC-001 together.release: cut a release, asdocs/releasing.mddescribes.steward: take a pull request to green.- The
reviewersubagent reviews a diff against AGENTS.md, this file and the docs' drift tests. - The
claims-checkersubagent checks every number in changed prose against the claims ledger, the results pages and the paper.
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.

