English | 简体中文

Joyczl-agent

A local-first personal assistant: Rust owns logic and state, TypeScript
covers the browser and chat gateways, Python stays a thin SDK. The state
store, reasoning, and tools all run on the user's own machine. Codename
Joy — the assistant's persona is Joy too.

Design principles

1. Rust owns logic and state. The agent loop, memory, tools, and
   state.db live in Rust; crates are split by responsibility (target <500
   lines per module), with no joy-core mega-crate.
2. The protocol has one definition. joyczl-protocol is the single
   source of truth for the cross-language contract: types generate the
   TypeScript and Python bindings, and the artifacts are checked in.
3. Clients only translate. The CLI, dashboard, chat gateways, and Python
   SDK are all clients of joy app-server (JSON-RPC over stdio); state.db is
   opened by exactly one process.

Quick start

cd joy-rs && cargo build
JOY_PROVIDER=deepseek DEEPSEEK_API_KEY=… ./target/debug/joy       # terminal REPL
JOY_PROVIDER=deepseek DEEPSEEK_API_KEY=… ./target/debug/joy dashboard   # → http://localhost:7777

A turn over raw protocol:

ANTHROPIC_API_KEY=sk-… JOY_HOME=/tmp/joy-demo ./target/debug/joy app-server <<'JSONRPC'
{"jsonrpc":"2.0","id":1,"method":"turn/start","params":{"message":"Remember that Alex likes morning meetings"}}
JSONRPC

The response follows a notification stream: turnStarted → gateDecided → textDelta* → toolStarted → toolCompleted* → turnCompleted. turnCompleted.meta
records the gate ruling, tool timing, which model answered, and token usage —
persisted with the conversation.

What Joy can do

• Converse on the terminal, in the dashboard, or through chat gateways
  (Telegram, Discord, WeChat, Lark — see docs/gateways.md)
• Remember: semantic facts (FTS5, CJK-capable), dated episodes, and
  procedural Skills — with a retrieval gate so memory is consulted only when
  relevant (docs/architecture.md)
• Act: 11 built-in tools plus MCP servers
  (docs/configuration.md)
• Plan as a graph: the triage front door answers small talk cheaply; the
  gather workflow writes a morning brief
  (docs/architecture.md)
• Be examined: deterministic evals gate every release; a judge grades
  answer quality (docs/testing.md)
• Be observed: every turn lands a trace line and a usage row
  (docs/architecture.md)

Built-in tools

Twelve LLM providers are pre-adapted in code (joyczl-provider), switchable at will: /model lists configured profiles, /model add ds deepseek deepseek-chat --env DEEPSEEK_API_KEY adds one, /model use ds switches — no need to retype the key, effective immediately, no restart. The dashboard's "Model" panel is the same implementation. Keys go to the OS keychain first, falling back to <home>/secrets.json (0600, plaintext) when there is none — the save response says which one it was, honestly. The old JOY_API_KEY / JOY_BASE_URL env vars are no longer read — configuration has exactly one path: models.json.
| fetch_url | fetch a page's text (HTML→plain, 50k cap); SSRF guard (blocks private/metadata targets, re-checks every redirect) + an external-content-is-data declaration |
| create_skill | persist an agreed workflow as procedural memory |
| job_output / job_list / job_kill | read, list and stop background jobs (started with run_command's background=true) |
| todo_write | keep a per-session todo list, re-injected every turn (whole-table replace; one in_progress at a time) |
| current_time | local time with weekday and timezone |
| run_command | shell commands — sandboxed, allowlisted, off unless JOY_EXEC=1 (SECURITY.md) |
| delegate_task | hand one self-contained job to a subagent — off unless JOY_DELEGATE=1, cannot delegate again; pass result_schema for a structured answer (retried once, then prose) |

Tool failures return to the model as text — the loop never crashes on one.

Documentation

Roadmap

Naming

English | 简体中文 · Code is MIT.