agentleFS
ChrisVip001ChrisVip001/joyczl-agent/AGENTS.md

joyczl-agent

AGENTS.md112 starsChanged 4 days agoMITView on GitHub

English | 简体中文 Joy is a local-first personal assistant: Rust owns logic and state, TypeScript covers the browser and the chat gateways. Read docs/architecture.md before changing joy-rs/; this file is the working standard for AI coding assistants and human contributors alike. - The protocol has one definition: types live only in joyczl-protocol/src/protocol/v2.rs; after changing them run just write-app-server-schema and commit the artifacts. Wire fields are camelCase, integers are i32, new types go into the export.rs list. - Tool errors are…

  • 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

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

2 rules. About 0 are common, 1 is distinctive, and 1 is 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.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read docs/architecture.md before changing joy-rs/.

    line 7
  2. Distinctive:

    No heavy new dependencies: check the workspace for an equivalent first (URL codecs and hashing already exist here).

    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

AGENTS.md

English | 简体中文

Joy is a local-first personal assistant: Rust owns logic and state, TypeScript covers the browser and the chat gateways. Read docs/architecture.md before changing joy-rs/; this file is the working standard for AI coding assistants and human contributors alike.

Repository layout

joy-rs/
  joyczl-protocol/      the cross-language contract, single source of truth
                        (schema/ artifacts are checked in)
  joyczl-config/        JOY_* environment variables, read once at boot
  joyczl-schedule/      scheduling, one implementation: five-field cron + `schedules.json`
                        (declarations.rs). `joy schedule` fires on it, the capability center
                        predicts with it, `schedule_job` / `list_schedules` /
                        `cancel_schedule` write through it
  joyczl-state/         SQLite + FTS5(trigram); the append-only ledger; memory-backend contract & conformance
  joyczl-provider/      12 providers (incl. local Ollama), two wire formats + SSE, retry + token estimation
  joyczl-tools/         tool registry (schema-checked) + built-in tools, sandboxed exec, subagents,
                        approval, lifecycle hooks, the todo list, the background-job host trait
  joyczl-loop/          the agent loop (cancellable)
  joyczl-graph/         wave-based DAG engine + triage / gather workflows
  joyczl-mcp/           MCP client (stdio/HTTP) + browser OAuth + memory server (`joy mcp serve`)
  joyczl-memory/        retrieval gate + consolidation + Skills + the OKF bundle in `home/memory`
                        (bundle.rs, mirror.rs) + MEMORY.md mirror
  joyczl-app-server/    JSON-RPC over stdio, the only holder of state.db, and with it the whole turn:
                        approval, hooks, todo injection, background jobs, the goal loop; the ledger
                        writer, the background memory worker, the memory center, and prompt assembly
                        (stable prefix + per-turn tail)
  joyczl-ops/           dashboard backend (axum + SSE)
  joyczl-cli/           the joy binary (REPL / dashboard / gather / eval / mcp / skill)
  joyczl-eval/          deterministic evals + judge + release gate
joy-ts/                 @joy/client, @joy/gateway, @joy/dashboard
evals/                  deterministic and judge scenarios (JSONL)
docs/                   architecture / configuration / protocol / testing / operations / skills / limitations
                        internals/ — the implementation tutorial (one chapter per layer)
scripts/                schema generation + four end-to-end smokes

Commands

just check                    # every gate: fmt + schema drift + tool docs drift + ts-check
                              # + py-check + clippy -D warnings + cargo test + deterministic eval
just check-tool-docs          # 06-tools §6.0 / README 的工具表 vs. 代码里的工具名单
just check-i18n               # 驾驶舱 t("…") 的每条文案 vs. i18n.ts 的英文表
just eval / just judge        # deterministic eval (exit 0 = releasable) / judge scores
just write-app-server-schema  # required after any protocol change;
                              # just check-app-server-schema is the CI drift check
just smoke smoke-gateway smoke-dashboard smoke-sdk-python   # end-to-end smokes

Non-negotiable invariants

  • The protocol has one definition: types live only in joyczl-protocol/src/protocol/v2.rs; after changing them run just write-app-server-schema and commit the artifacts. Wire fields are camelCase, integers are i32, new types go into the export.rs list.
  • Tool errors are text, not exceptions: ToolRegistry::execute never returns Err.
  • Fail-open paths need tests: the retrieval gate, triage, and gather failure paths matter as much as the success paths.
  • Zero clippy warnings (-D warnings); target <500 lines per crate module.
  • Configuration comes from environment variables; config/write patches are validated and rejected wholesale — invalid values never reach settings.json.
  • No heavy new dependencies: check the workspace for an equivalent first (URL codecs and hashing already exist here).
  • Credentials have three sources, in fixed priority: environment variable (highest — Joy reads it, never copies it) → the OS keychain (macOS Keychain / Linux secret-service) → <home>/secrets.json (0600, plaintext fallback, only when no keychain is usable; Windows has no credential API that reads secrets back, so it lands there directly). Responses and logs only ever carry a pointer to where the key lives, never the key itself; OAuth tokens go to mcp-auth/ (0600).
  • Propose, never act: the gather graph stays tool-free; send_message never actually sends.
  • Extensions are injected: the tool layer knows only traits (SubagentRunner, ApprovalBroker, HookRunner, JobRegistry); every implementation lives in app-server and ToolCtx only gains fields. The dependency points one way — the other way is a cycle.
  • Capabilities are switched on by humans: JOY_EXEC / JOY_DELEGATE / JOY_WRITE / JOY_HOOKS are off by default, and the paths only a human may start (approval, goals, memory writes) are not exposed to the model at all — no tool, no route. "The model assigning itself work" is not forbidden here, it is impossible.
  • Never silent: retries, circuit breaking, skipped duplicate writes, goal rounds, finished background jobs and hooks refused by a trust hash each owe the user a stderr line or a protocol notification. Watching a frozen screen and guessing why is the class of problem this round kept fixing.

Testing

Behavior changes come with tests: unit tests live inside each crate, cross-module assembly behavior lives in evals/deterministic/*.jsonl (one case per line; multi-turn, prompt assertions, interruption, and config injection are supported). Reproduce a bug in a test before fixing it. A failing joy eval blocks release.

Docs

User-visible behavior changes update the README and the matching docs/ booklet in the same change. Documentation is written in English as the primary language with a .zh.md Chinese twin per file; update both together. One fact per home, no control-flow narration.

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.