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.
- video-transcriptionSkill
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
- Very specific: line 7
Read docs/architecture.md before changing joy-rs/.
- Distinctive: line 72
No heavy new dependencies: check the workspace for an equivalent first (URL codecs and hashing already exist here).
≈ “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
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 smokesCommands
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 smokesNon-negotiable invariants
- The protocol has one definition: types live only in
joyczl-protocol/src/protocol/v2.rs; after changing them runjust write-app-server-schemaand commit the artifacts. Wire fields are camelCase, integers arei32, new types go into theexport.rslist. - Tool errors are text, not exceptions:
ToolRegistry::executenever 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/writepatches 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 tomcp-auth/(0600). - Propose, never act: the gather graph stays tool-free;
send_messagenever actually sends. - Extensions are injected: the tool layer knows only traits (
SubagentRunner,ApprovalBroker,HookRunner,JobRegistry); every implementation lives in app-server andToolCtxonly 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_HOOKSare 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.
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.

