yolop
AGENTS.md18 starsChanged 13 days agoMITView on GitHub
Yolop is a terminal coding agent built on everruns-core. The binary and the crate are both named yolop. This file is read on every turn. It carries repository facts and gotchas only; depth lives behind the links below. knowledge/specs/agent-context.md defines how this repository organizes what agents read. Telegraph, keep updates short and factual. Fix root causes; when you are still stuck after reading the code, ask with short options. Prose in this repository, knowledge/, docs, commit messages, and PR bodies…
- Reads credentials
- Installs packages
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 32,671 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.
- CLAUDE.mdCLAUDE.md
- author-extensionSkill
- maintenanceSkill
- releaseSkill
- shipSkill
The file
We split this AGENTS.md into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
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 59
Never write #[ignore] tests, an ignored test is one nothing ever runs, and neither cargo test nor CI passes --ignored.
- Distinctive: line 124
When a change alters durable behavior, intent, architecture, policy, constraints, terminology, or maintainer process, update the affected …
- Very specific: line 137
Never add Claude/session/AI attribution to commits, PRs, docs, or comments.
- Distinctive: line 138
Commit attribution must be a real human user.
- Very specific: line 141
Start from latest main by default: git fetch origin main, then branch from or rebase onto origin/main.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 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
Yolop, coding-agent guidance
Yolop is a terminal coding agent built on
everruns-core. The binary and
the crate are both named yolop.
This file is read on every turn. It carries repository facts and gotchas only;
depth lives behind the links below. knowledge/specs/agent-context.md
defines how this repository organizes what agents read.
Telegraph, keep updates short and factual. Fix root causes; when you are still stuck after reading the code, ask with short options.
Prose in this repository, knowledge/, docs, commit messages, and PR bodies
alike, uses no em-dashes: a comma, colon, or separate sentence says the same
thing without the AI tell. knowledge/log.md headings are ## DATE, Title.
Layout
A Cargo workspace of two packages; root cargo test / cargo clippy cover
both.
., theyolopbinary.crates/yolop-yep/, the YEP extension protocol and server SDK, published separately for extension authors; the host depends on it for the wire types.
Both renderers are built on tuika, a
terminal-UI toolkit that lives in its own repository and is consumed from
crates.io along with its tuika-codeformatters highlighter and tuika-mermaid
renderer: the default renderer is tuika's alternate-screen mode, and --inline
its split-footer mode. See Tuika.
Gotchas
Secrets come from Doppler.
OPENAI_API_KEYis the default provider key,ANTHROPIC_API_KEYthe secondary; CI loads both from theDOPPLER_TOKENrepository secret.doppler run -- cargo test --workspace --features yolop-yep/schema doppler run -- cargo run -- --provider openai -p "hi"- Try
ghdirectly first. Only if it reports that it is not authenticated, retry through Doppler, do not reach for Doppler preemptively:doppler run -- bash -lc 'GH_TOKEN="$GITHUB_TOKEN" <command>'. --provider llmsimneeds no API key, socargo run -- --provider llmsim -p "hi"is the offline smoke test.- Yolop is pre-1.0: no backward compatibility is required unless a spec says so.
- Unrecognized working-tree changes are probably from another agent or the user. Work with them; stop only if they make the task unsafe.
- Decisions worth keeping belong as concise comments near the relevant code, not in scratch documents.
- For bug fixes, prefer writing the failing test before the fix.
- Changelog is part of done. A PR that completes a user-facing feature or fix adds a public changelog entry on
everruns.com/docs: a companion PR in everruns/everruns adds
docs/changelog/<date>-<slug>/, merged right after this one. Fill the PR template'sChangelog:line (companion PR, the program it is part of, ornot user-facing). Rules: https://github.com/everruns/everruns/blob/main/knowledge/docs/changelog.md - Never write
#[ignore]tests, an ignored test is one nothing ever runs, and neithercargo testnor CI passes--ignored. A test that needs something the environment may lack checks for it at runtime and returns early: a key vialive_key_or_skip, a binary via a probe, an external service viaYOLOP_REQUIRE_LIVE_TESTS. CI's live-smoke job sets that flag, which turns a missing key into a hard failure so a misconfigured secret cannot report green.
RUST_LOG is honored for the tracing layer: stderr outside the interactive TUI,
private rotating files under <data_dir>/yolop/logs/ inside it.
The dev profile carries line tables, not full DWARF, so backtraces keep
file and line while target/ stays a few gigabytes smaller. A debugger that
needs variable inspection wants cargo build --profile dev-debuginfo.
Checks
--features yolop-yep/schema, not --all-features: the schema feature resolves
to the same crates a default build does, while --all-features also turns on
local-inference and its ~220-crate engine. Mixing the two feature sets in one
target/ compiles the whole graph twice; keep every routine command on the same
one. --workspace is what makes the root commands cover both packages, and with
it the wire-schema drift guard in yolop-yep.
cargo fmt --check
cargo clippy --workspace --all-targets --features yolop-yep/schema -- -D warnings
cargo test --workspace --features yolop-yep/schema
python3 scripts/validate_okf.py knowledge --check-links # when knowledge/ changedTouching anything behind local-inference (src/drivers/local.rs,
src/models/) needs the engine compiled too. Give it its own target directory
so it stays out of the routine one:
CARGO_TARGET_DIR=target-local-inference \
cargo clippy --workspace --all-targets --features local-inference -- -D warningsThe release ships an accelerated build per target (metal on macOS, cuda on
Linux), so a change there wants the backend compiled too. cuda needs nvcc
(apt-get install nvidia-cuda-toolkit) and CUDA_COMPUTE_CAP set, since the
kernels are compiled for one capability and there is no GPU here to ask:
CARGO_TARGET_DIR=target-cuda CUDA_COMPUTE_CAP=80 \
cargo check -p yolop --locked --features cudaWhere things live
knowledge/, the OKF bundle and durable development memory: intent, architecture, policy, constraints, and the success bars for shipping, maintenance, and release. Read the index first, then only the concepts the task touches..agents/skills/, workflows the user can request by name:/ship,/maintenance,/release,/author-extension.evals/README.md, the Mira eval studies (SWE-bench Verified, harness A/Bs, LSP isolation). Outside the Cargo workspace.README.mdanddocs/, the public surface. Neither may link intoknowledge/or.agents/; seeknowledge/specs/documentation.md.
Keeping knowledge current
When a change alters durable behavior, intent, architecture, policy,
constraints, terminology, or maintainer process, update the affected concepts in
the same change. Update knowledge/index.md when concepts are added, removed,
renamed, or reclassified, and knowledge/log.md for significant knowledge
changes. Transient plans, task status, and source-level detail stay out of the
bundle.
Commits
- Conventional Commits:
type(scope): description, usingfeat,fix,docs,refactor,test, orchore.chorecoversknowledge/,AGENTS.md, and CI metadata. - Stage files explicitly by name. Avoid
git add ./git add -A. - Never add Claude/session/AI attribution to commits, PRs, docs, or comments.
- Commit attribution must be a real human user. If the git identity is missing or agent-like, stop and ask before committing.
Start from latest main by default: git fetch origin main, then branch from or
rebase onto origin/main. The merge bar (PR template, CI, squash) is owned by
knowledge/specs/shipping.md.
Tuika
Toolkit-shaped work, layout, components, overlays, focus, keymap, markdown
rendering, terminal escapes, screen modes, belongs in
everruns/tuika, not here; what belongs here
is how yolop composes it. Land a needed toolkit change there, release it, then
bump the version, a git dependency would make yolop unpublishable.
Terminal protocol verification lives upstream with tuika's own gallery and tmux gate. See knowledge/specs/tuika.md.
Upstream relationship
Yolop began as a friendly fork of the examples/coding-cli example in
everruns/everruns. As of 0.17.24 that
example is no longer a mirror source, upstream rebuilt it as a minimal
acceptance test for the new everruns facade crate and deleted its TUI, MCP,
and provider wiring. Track the everruns-* library surface and upstream's
CHANGELOG.md instead, and keep the crate versions in lockstep with what is
published on crates.io. See
knowledge/specs/maintenance.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.

