agentleFS
koharu-rskoharu-rs/koharu/AGENTS.md

koharu

AGENTS.md6.7k starsChanged 2 months agoApache-2.0View on GitHub

Koharu is a local-first manga translator: a Rust workspace with a TypeScript interface, shipped as a desktop app. This file holds durable decision rules only. Architecture, file layouts, crate and helper names, model inventories, commands, and anything else a refactor can change belong in crate READMEs and the docs. Normal Rust, TypeScript, testing, formatting, and Git practices are assumed.

1 other project uses a version of this.

Trending

More talk lately.thin dataabout the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 0 mentionsJul 2026: 0 mentionsAug 2026: 1 mentionSep 2026: 2 mentionsOct 2026: 3 mentionsNov 2026: 0 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the koharu-rs/koharu repository that our weekly crawl found: only 6 in all, so this is a hint, not a trend. There is no adoption data for this file yet.

Most recently taken up by

Who's talking about koharu-rs/koharu

The biggest 5 of 6 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 6

Talked about on GitHub and Bluesky (6 times).

On GitHub · 5

On Bluesky · 1

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. mayocream/koharu★ 6.7k100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • 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 repositoryOne other file it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

18 rules. About 1 is common, 15 are distinctive, and 2 are very specific to this project.

  • ≈1

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈15

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Never add backward compatibility, except that a project file a release wrote keeps opening.

    line 13
  2. Distinctive:

    Prefer a coherent ownership redesign over cosmetic renaming.

    line 15
  3. Distinctive:

    When two changes implement the same workflow, keep one and extend the existing command or configuration.

    line 17
  4. Distinctive:

    If the code you are changing has moved, rebase onto its new owner.

    line 18
  5. Distinctive:

    Write the smallest code that does the job.

    line 23
  6. Distinctive:

    Keep safe public APIs apart from unsafe FFI, dynamic loading, and build integration.

    line 25
  7. Distinctive:

    Do not hand-edit generated or derived source.

    line 26
  8. Common:

    Do not commit credentials, model weights, datasets, generated outputs, or machine-specific files.

    line 28
  9. Very specific:

    Search with rg, never grep.

    line 29
  10. Distinctive:

    Do not show status the current selection already implies.

    line 36
  11. Distinctive:

    Use the existing control library for standard interaction.

    line 37
  12. Distinctive:

    Every model has the same public lifecycle, with model-specific inputs and outputs.

    line 43
  13. Distinctive:

    Use the established loading paths unless they are proven insufficient.

    line 45
  14. Distinctive:

    Remove redundant transfers, synchronization, allocations, and per-pixel host loops before adding concurrency or caching.

    line 51
  15. Distinctive:

    Run the smallest relevant check or focused test once, in the debug profile.

    line 56
  16. Distinctive:

    Do not use computer use on Windows.

    line 66
  17. Distinctive:

    Keep pull-request text short: problem, change, and verification.

    line 71
  18. Very specific:

    Never add an AI assistant as a commit co-author, for example through a Co-Authored-By trailer.

    line 72

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

Working on Koharu

Koharu is a local-first manga translator: a Rust workspace with a TypeScript interface, shipped as a desktop app. This file holds durable decision rules only. Architecture, file layouts, crate and helper names, model inventories, commands, and anything else a refactor can change belong in crate READMEs and the docs. Normal Rust, TypeScript, testing, formatting, and Git practices are assumed.

Product

  • Models run on the user's machine. Pages and text leave it only through a hosted provider the user chose.
  • Editor behavior that is not already specified matches Photoshop or Clip Studio Paint. Ordinary editing happens in the app, not through an export and re-import round trip.
  • Desktop API keys and sign-in tokens are stored encrypted, with the key kept in the OS credential store. Do not fall back to a project environment file.

Changes

  • Never add backward compatibility, except that a project file a release wrote keeps opening. When an API, schema, file format, configuration, or ownership boundary changes, delete the replaced form: no alias, forwarding layer, compatibility parser, upgrade decoder, stub, or disabled flag.
  • Changing a released project format ships an upgrade to the new one, which leaves the file as it was if it fails. A format no release wrote gets no upgrade.
  • Prefer a coherent ownership redesign over cosmetic renaming. Defaults and provider-specific behavior belong to the component that owns them, not to a central list of special cases.
  • Make the smallest change that solves the problem. Leave unrelated configuration, documentation, generated files, and workflows alone. A feature does not land beside drive-by cleanup.
  • When two changes implement the same workflow, keep one and extend the existing command or configuration.
  • If the code you are changing has moved, rebase onto its new owner. Do not port a patch onto a deleted tree.
  • Invalid configuration and model output fail closed. A project file fails to open only when it doesn't parse, isn't this app's format or version, or would crash a reader; its structure is kept by the operations that write it, not checked again. Do not add a repair or defaulting layer that can change meaning.

Code

  • Write the smallest code that does the job. Inline a helper with one caller, keep a small module in its parent, and do not wrap a type without adding a responsibility.
  • Reach for a crate before writing code: a well-known external crate first, then one in this repository. Hand-write only what no crate covers, and prefer a cross-platform crate to per-platform branches.
  • Keep safe public APIs apart from unsafe FFI, dynamic loading, and build integration.
  • Do not hand-edit generated or derived source. Change its input and rerun the generator.
  • Comments explain ownership, invariants, upstream mapping, or a deliberate divergence. Do not narrate straightforward code.
  • Do not commit credentials, model weights, datasets, generated outputs, or machine-specific files.
  • Search with rg, never grep.

Interface

  • User-visible strings go through the translation function and the locale files. Hardcoded English in a translated surface is incomplete.
  • An interface language's display name is that language's own name in every locale.
  • The translation-target language list stays in the active UI language. Drop a country name unless the entry is a real variant.
  • Do not show status the current selection already implies. Do not add a second job kind, cancel path, or counter for an operation an existing command covers.
  • Use the existing control library for standard interaction. Commit on selection or an uncanceled drop, never on focus or hover. Ignore a canceled drag. A shortcut never steals keys from a focused control.

Models

  • A port stays structurally traceable to a commit-pinned upstream implementation. Preserve checkpoint-affecting names, construction order, parameter paths, tensor layouts, execution order, and postprocessing semantics. Explain each intentional divergence next to the affected code.
  • Missing or unexpected weights mean an architecture or parameter-name mismatch. Fix that before changing the loader.
  • Every model has the same public lifecycle, with model-specific inputs and outputs. Network and weight loading stay apart from preprocessing, postprocessing, slicing, and result types. Do not add pass-through types or layers.
  • Accept a device at the model boundary and convert it once. Create token IDs and index tensors on the model device; a CPU tensor used against accelerator embeddings is a defect.
  • Use the established loading paths unless they are proven insufficient.
  • Disable gradient tracking during inference.

Performance

  • Optimize and benchmark on the actual target device with representative inputs. Load assets and warm models outside the measured region, and account for asynchronous accelerator execution.
  • Remove redundant transfers, synchronization, allocations, and per-pixel host loops before adding concurrency or caching.
  • Report the device, input size, baseline, result, and correctness difference.

Verification

  • Run the smallest relevant check or focused test once, in the debug profile. Run full suites, other profiles, or end-to-end tests only when asked.
  • Add a test only where it protects a real regression boundary. Do not lock a translated phrase, a language display name, a registration string, or a one-line behavior the owner can read. Do not add a second harness for behavior existing tests cover, a test of a compatibility shim, or a benchmark nobody asked for.
  • A model port needs a structured comparison with upstream on identical inputs: shapes, ranges, boxes, scores, masks, and ordering. A green build is not that comparison.
  • A UI change needs a screenshot of the affected state. For truncation, include a long label.
  • A green check is not acceptance.

Testing

  • Automate the UI through a Chrome DevTools Protocol MCP server connected to http://127.0.0.1:4000, the debug build's remote debugging endpoint.
  • Capture the canvas with the harness's built-in screenshot tool.
  • Do not use computer use on Windows.

Contributing

  • A human reviews the whole diff and can explain every change. Do not submit an unreviewed autonomous patch.
  • Keep pull-request text short: problem, change, and verification.
  • Never add an AI assistant as a commit co-author, for example through a Co-Authored-By trailer.

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.