agentleFS
everrunseverruns/yolop/AGENTS.md

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.

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
  1. Very specific:

    Never write #[ignore] tests, an ignored test is one nothing ever runs, and neither cargo test nor CI passes --ignored.

    line 59
  2. Distinctive:

    When a change alters durable behavior, intent, architecture, policy, constraints, terminology, or maintainer process, update the affected …

    line 124
  3. Very specific:

    Never add Claude/session/AI attribution to commits, PRs, docs, or comments.

    line 137
  4. Distinctive:

    Commit attribution must be a real human user.

    line 138
  5. Very specific:

    Start from latest main by default: git fetch origin main, then branch from or rebase onto origin/main.

    line 141

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

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

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.

  • ., the yolop binary.
  • 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_KEY is the default provider key, ANTHROPIC_API_KEY the secondary; CI loads both from the DOPPLER_TOKEN repository secret.

    doppler run -- cargo test --workspace --features yolop-yep/schema
    doppler run -- cargo run -- --provider openai -p "hi"
  • Try gh directly 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 llmsim needs no API key, so cargo 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's Changelog: line (companion PR, the program it is part of, or not 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 neither cargo test nor CI passes --ignored. A test that needs something the environment may lack checks for it at runtime and returns early: a key via live_key_or_skip, a binary via a probe, an external service via YOLOP_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/ changed

Touching 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 warnings

The 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 cuda

Where 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.md and docs/, the public surface. Neither may link into knowledge/ or .agents/; see knowledge/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, using feat, fix, docs, refactor, test, or chore. chore covers knowledge/, 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.

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.