Repolode
Submit
ChrisVip001

ChrisVip001/joyczl-agent

A local-first personal assistant with a Rust core for the agent loop, memory and tools, plus TypeScript chat gateways and a dashboard.

View on GitHub
Stars
112
Forks
0
Open issues
0
Last commit
3 days ago

What is it?

Joy is a personal assistant that runs on the user's own machine. Its state store, agent loop, memory and tools are implemented in Rust, while TypeScript provides the browser dashboard and chat gateways for Telegram, Discord, WeChat and Lark. A thin Python SDK wraps the same JSON-RPC interface exposed by the `joy app-server` process, so every client talks to one place that owns the SQLite state.

Memory combines semantic facts searchable with FTS5, dated episodes, and procedural Skills, with a retrieval gate that consults memory only when it seems relevant. The assistant ships with about eleven built-in tools covering notes, calendar events, web search, file reading, URL fetching and shell commands, and it can connect to MCP servers. Shell execution is off by default and requires an explicit environment flag. Each turn records a trace line and token usage.

The project includes a deterministic evaluation suite and an LLM judge for answer quality, and it supports a range of LLM providers including local Ollama models that need no API key.

Key features

  • 01Chat through a terminal REPL, a browser dashboard, or Telegram, Discord, WeChat and Lark gateways.
  • 02Three memory types: searchable facts, dated episodes, and reusable Skills.
  • 03Built-in tools for notes, calendar, web search, file reading and URL fetching, plus MCP server support.
  • 04Shell commands are sandboxed, allowlisted, and disabled unless explicitly enabled.
  • 05Clients communicate with the core over JSON-RPC, with SQLite state owned by a single process.

Use cases

  • Running a private assistant that keeps notes, memory and calendar data on your own machine.
  • Chatting with an agent from Telegram or Discord while the state stays local.
  • Experimenting with a Rust agent core that exposes a JSON-RPC API to other clients.
  • Using a local Ollama model as the assistant's LLM without sending data to a cloud provider.

Quick start

  1. 1

    Build the Rust project from the joy-rs directory

    cd joy-rs && cargo build
  2. 2

    Start the terminal REPL with a provider and API key

    JOY_PROVIDER=deepseek DEEPSEEK_API_KEY=… ./target/debug/joy
  3. 3

    Or start the dashboard at http://localhost:7777

    JOY_PROVIDER=deepseek DEEPSEEK_API_KEY=… ./target/debug/joy dashboard

Things to know

  • Requires building from source with Cargo, since no package is published to PyPI or npm yet.
  • Needs an LLM provider API key, or a local Ollama setup, before it can answer.
  • The Discord, WeChat, and Lark gateways have never been connected to the real platforms.

In collections

Open-source AI agent frameworks & appsMCP serversPrivacy & local-first toolsDatabases & SQL toolsOpen-source personal AI agents

Topics

#agent#local-first#personal-assistant#rust#mcp#llm#sqlite#json-rpc#agent-framework#ai-agent

FAQ

What is joyczl-agent?
A local-first personal assistant with a Rust core for the agent loop, memory and tools, plus TypeScript chat gateways and a dashboard. Joy is a personal assistant that runs on the user's own machine. Its state store, agent loop, memory and tools are implemented in Rust, while TypeScript provides the browser dashboard and chat gateways for Telegram, Discord, WeChat and Lark. A thin Python SDK wraps the same JSON-RPC interface exposed by the `joy app-server` process, so every client talks to one place that owns the SQLite state.
Is joyczl-agent free to use? What license does it have?
joyczl-agent is open source under the MIT license. Check the license terms before using it in commercial products.
Is joyczl-agent still maintained?
Actively maintained. The last commit to joyczl-agent was on Nov 4, 2026.
What can I use joyczl-agent for?
Running a private assistant that keeps notes, memory and calendar data on your own machine. Chatting with an agent from Telegram or Discord while the state stays local. Experimenting with a Rust agent core that exposes a JSON-RPC API to other clients. Using a local Ollama model as the assistant's LLM without sending data to a cloud provider.
How do I install joyczl-agent?
Build the Rust project from the joy-rs directory: cd joy-rs && cargo build Start the terminal REPL with a provider and API key: JOY_PROVIDER=deepseek DEEPSEEK_API_KEY=… ./target/debug/joy Or start the dashboard at http://localhost:7777: JOY_PROVIDER=deepseek DEEPSEEK_API_KEY=… ./target/debug/joy dashboard
Where can I get joyczl-agent?
The source code and installation instructions are on GitHub: https://github.com/ChrisVip001/joyczl-agent

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects