Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/shiwenwen/hope-agent

会记忆、能成长的随身 AI 助手 · 桌面 / 云端 / IM 随叫随到，手机远程也能连 | Personal AI that remembers and grows — lives on desktop, self-hosted server and every IM, reachable anywhere
https://github.com/shiwenwen/hope-agent

agent ai ai-assistant anthropic chatbot claude claw codex desktop-app gemini harness hermes-agent llm local-ai mcp openai openclaw personal

Last synced: about 1 month ago
JSON representation

会记忆、能成长的随身 AI 助手 · 桌面 / 云端 / IM 随叫随到，手机远程也能连 | Personal AI that remembers and grows — lives on desktop, self-hosted server and every IM, reachable anywhere

Awesome Lists containing this project

README 

          


  Hope Agent




Hope Agent





  A desktop AI assistant that hands off across your devices and gets to know you better the more you use it — also runs headless, on a NAS or in the cloud.


  Remembers you · Grows over time · Deeply OS-integrated · Reachable from every chat app you use






  CI status

  macOS

  Linux (experimental)

  Windows (experimental)

  Web GUI

  Rust

  Tauri

  React

  License: MIT






  简体中文 · English




---



**Hope Agent** is an AI assistant built to stay simple, stable, and low-maintenance. The same conversation hands off seamlessly between your devices and chat apps, and gets better the more you use it — cross-session memory accumulates, idle time gets spent organizing what mattered, and the things you've done crystallize into reusable skills. One native installer, GUI templates for the major model providers baked in, paste an API key and you're chatting; on desktop it can also observe and control your computer after you grant permission (currently macOS only); it also runs as a background service on a NAS, home server, or cloud VM, staying reachable through your IM apps wherever it lives.



## Contents



- [Why Hope Agent](#why-hope-agent)

- [Highlights](#highlights)

- [Quick Start](#quick-start)

  - [Install Locally](#install-locally)

  - [Self-hosting (Docker)](#self-hosting-docker)

  - [For developers](#for-developers)

- [Run Modes](#run-modes)

- [Ecosystem](#ecosystem)

- [Project Structure](#project-structure)

- [Documentation](#documentation)

- [Contributing](#contributing)

- [Community](#community)

- [Acknowledgements](#acknowledgements)

- [Star History](#star-history)

- [License](#license)



## Why Hope Agent



We want an AI assistant that just **opens and works**: download an installer, install it, no runtimes or CLI to learn, no cryptic config to decipher, no service quietly crashing at 3am with no one to fix it, **and picks up wherever you go**. Hope Agent isn't only a desktop app — it also runs as an HTTP/WS service you can park on a NAS, home server, or cloud VM and leave running 24/7, while it hooks into IM channels and talks to IDEs over ACP — but we believe the easiest entry point is still the desktop, so that's where we put the most effort: **a first-class desktop GUI deeply integrated with the OS**, polished together with performance, stability, and the small interaction details. The goal is plain: reduce the cost of using and maintaining an AI assistant, make simple workflows feel effortless, and keep long-running setups dependable. And we want it to grow with you over the long run — one conversation that follows you across devices, chats, and platforms, with memory and skills quietly accruing along the way.



> Hope Agent was influenced in its early days by [openclaw](https://github.com/openclaw/openclaw) — credit to them for their pioneering work on local AI assistants. We took a different implementation path.



## Highlights



### 🎯 Everyday use



🖥️ Native desktop GUINative macOS / Linux / Windows app, ready to run out of the installer. Ships in 12 UI languages (Simplified/Traditional Chinese, English, Japanese, Korean, Spanish, Portuguese, Russian, Arabic, Turkish, Vietnamese, Malay) with a polished dark theme and carefully tuned typography.

🧙 Zero-config providers39 built-in provider templates covering 206 preset models. Anthropic, OpenAI, Gemini, Codex, OpenRouter, DeepSeek, Kimi, Qwen, Doubao, GLM, MiniMax, xAI, Mistral, Cerebras, DeepInfra, Tencent Hunyuan, Ollama — all in. Each provider supports multi-key rotation, so rate limits and quota exhaustion fail over seamlessly to the next key.

🦙 One-click local modelsNo account, no API key, no terminal — Settings → Model picks a Qwen3.6 / Gemma 4 size that fits your hardware, then handles Ollama install, model pull, provider registration, and active-model switch in one click. Same flow covers local embedding models too.

💬 One app, every chat12 IM channels: Telegram, Discord, Slack, Feishu, Google Chat, LINE, QQ Bot, Signal, iMessage, IRC, WeChat, WhatsApp. Inbound images / voice / files become multimodal context automatically; tool approvals are one tap in the chat window; every group / account can bind a distinct Agent with its own policies.

🤝 Hand off across devices, never miss a beatThe same conversation hands off seamlessly between your desktop, browser, and IM — leave a thread half-finished on your laptop, pick it up on Telegram on the metro, come home and the desktop already has the IM portion folded in. The same memory, tool state, Plan, and working directory follow along — no need to re-explain context. /handover pushes the current desktop session to a specific IM chat; /session <id> takes over from inside IM. The desktop conversation also live-mirrors into IM, typing into Telegram / Feishu / Slack as the model writes.

🌐 Standalone service · browser is the clientNot just a desktop app — Hope Agent can run fully headless as a service. One command hope-agent server start launches an HTTP/WS daemon; server install registers it as a launchd / systemd auto-start unit so it lives 24/7 on your NAS, cloud VM, or spare laptop. The server ships an embedded Web GUI (the React frontend is baked into the binary via rust-embed) — point any browser on your phone, tablet, or another computer at http://<server>:port and you get the full React UI, no client install, no separate frontend deployment. Bearer token auth and three-tier SSRF policies keep public exposure controlled. Sessions, memories, cron jobs, and IM channels all run server-side — the client is just a window.

🔁 Three run modes, one coreDesktop GUI (default), HTTP/WS daemon with embedded Web GUI (browser-direct), and ACP stdio (as an agent backend for any ACP-capable IDE). All three share a pure-Rust ha-core library with zero Tauri dependencies — the same code is a desktop app, a server, and an IDE backend.



### 🧠 Memory & learning



🧠 Persistent memory across sessionsSQLite + FTS5 + vector search, three-in-one. Memories are scoped by Global / Project / Agent; system prompt injection follows a joint budget so no one layer crowds out another.

🕶 Incognito chatA per-session switch that can apply from the very first message. When enabled, the current chat gets no passive memory or cross-session awareness injection and does not auto-collect memory; memory tools are only used when you explicitly ask it to remember or recall something.

💤 Offline "dreaming"When idle, Hope Agent automatically reviews "what was worth remembering over the past couple of days," pins the selections, and writes them into a markdown diary viewable under Settings → Dream Diary. Every day's work gets quietly consolidated for next time.

🔍 Active recall + reflective profileBefore each turn starts, the most relevant memories for your input are pulled into the prompt (Active Memory). A separate reflective pass distills your communication style, work habits, and long-term preferences into a dedicated "User Profile" section — it gets better at knowing you over time.

🛠 Skills that growAfter complex tasks, Hope Agent auto-drafts new skills for your review. Approve a draft in settings and it's reusable from then on. Skills support conditional activation (e.g. only load when editing Python files), forked sub-agent execution, and tool allowlists; compatible with the agentskills.io open standard.

👁 Cross-session awarenessIt knows what your other chats are doing. Before each turn, Hope Agent pulls in the recent goals, actions, and friction points of your other active sessions — so when context crosses over, the right information is available without derailing the main conversation. Defaults to a zero-LLM-cost structured mode; an optional LLM digest mode is available.

💾 Long conversations don't lose the plotFive-tier progressive context compaction. No matter how long the chat, earlier messages aren't hard-truncated. Tool calls stay paired forever; when messages are summarized, recently edited file contents are auto-restored from disk so you don't have to paste them again. Combined with prompt caching, long-session API costs stay well below naive usage.



### 🛠 Workflow & tools



📋 Plan ModeFor complex tasks, Hope Agent first drafts an editable, resumable plan managed by a five-state machine, with plan files physically isolated per agent / session so cross-session bleed can't happen. Plans persist across sessions — "continue the previous plan" is enough to pick up. The sidebar Plans history viewer offers cross-session, read-only browsing of every plan (including /plan exit archives), with Agent / state filtering, version switching, and one-click jumps to the owning session; the detail pane injects an @plan:<short_id>:v<version> reference straight into the current chat. During execution it strictly respects a tool allowlist so the model can't wander.

📁 Project containersGroup related sessions under a single project that inherits project-level memory / instructions / shared files. Uploaded files get automatic text extraction and three-layer injection (dir listing / small-file auto-inline / large-file on-demand read) — no manual @ file, no context blowup.

🖱️ Computer controlCurrently macOS only. The Agent can use granted Accessibility and Screen Recording permissions to observe the desktop, inspect AX elements and windows, then open / switch apps, click, type, scroll, drag, use menus and dialogs, and move / resize / close windows. The Mac Control side panel mirrors desktop state in real time; every side-effecting action goes through the unified tool approval flow.

👥 Agent teamsPre-configure team templates in settings (member roles, bound agents, default task templates). One sentence tells the model to spin up a specialist team. Members message each other and coordinate; when done, the transcript is summarized back to the main thread.

🗓 Natural-language cron"Write me a daily summary every 8 AM." "Review last week's todos every Monday." "Scan my inbox hourly on workdays." Scheduled in plain language, delivered to any IM channel. Runs reliably under both desktop GUI and the daemon.

📊 Dashboard + RecapBuilt-in analytics: cost, token usage, activity heatmap, and a four-dimensional health score, plus a new Plans tab (state distribution, completion rate, breakdowns by Agent / Project, 30-day creation trend, average execution time). /recap runs a deep retrospective over the last N days and produces an 11-section AI report (Agent tool optimization, memory & skill recommendations, cost optimization, etc.) that exports as standalone HTML.

🔌 MCP client (OAuth 2.1)Built-in Model Context Protocol client with all four transports: stdio / Streamable HTTP / SSE / WebSocket. Full OAuth 2.1 + PKCE flow (automatic discovery, RFC 7591 dynamic client registration, loopback callback) persists credentials at 0600 on disk; standards-compliant OAuth servers like Notion / Linear work with a single click. All outbound URLs pass through the SSRF policy. One-click import from claude_desktop_config.json in Settings; tools surface as mcp__<server>__<tool> in the main conversation, with extra mcp_resource / mcp_prompt tools for passive data. Long-running tools auto-background.

🪝 Hooks automationHook custom handlers onto 28 lifecycle events — sessions, tool calls, context compaction, permission decisions, and more — field-level compatible with the Claude Code hooks protocol, so community scripts work as-is. Five handler types (command / http / mcp_tool / prompt / agent); config layers across user / managed / project / local scopes (UNIONed), and project-scope hooks (.hope-agent/hooks.json) ship with your repo for the whole team. Configure in a visual settings panel; changes hot-reload instantly.

🔧 ToolboxComputer control (currently macOS only), controllable browser (8 high-level actions with a live mirror panel on the chat sidebar — Chrome stays visible as the agent drives it; direct CDP via chromiumoxide, zero runtime dependencies), Canvas, AI image generation (7 providers), web search (8 providers with failover), bash (optional Docker sandbox), file read/grep/find, URL preview, crash journal, self-diagnosis.

📑 Deep Feishu / Lark workspace integration40 feishu_* tools spanning docx (create / read / edit), bitable (CRUD + views + dashboards), drive (upload / download ≤20MB, local paths gated by protected-path approval), wiki (link resolution), approval (create / query / cancel), calendar (create event / invite / update / delete), contact (user / department lookup), and hire (jobs / talents / applications). Reuses the existing Feishu IM channel credentials; ships with the skills/feishu skill that teaches typical workflows like OKR weekly reports, meeting scheduling, approval withdrawal.

⚡ Background long tasksLong-running shell commands, web searches, or image generations can be "sent to the background" — an immediate job_id returns so the conversation keeps flowing. The result is auto-injected back into the main thread when it finishes; the model can also poll with job_status on demand. No task is ever long enough to freeze your chat window.



### 🛡 Security & local-first



🔒 Tool approval + Docker sandboxSensitive tool calls are gated by an approval flow (with per-category auto deny / proceed timeouts and per-channel auto-approve). High-risk bash / file writes can be routed into an isolated Docker sandbox. Safe to give the Agent high privileges.

🏠 Local-first · zero third-party hopsAll data lives under ~/.hope-agent/: config, sessions, memories, attachments, skills, logs — all local SQLite / files. API keys hit model providers directly. In daemon mode, Bearer token auth plus three-tier SSRF policies keep remote access controllable.

🛟 Automatic config snapshots · one-click rollbackEvery config write auto-snapshots to backups/autosave/, keeping the last 50. Even if the model's settings tool garbles your preferences, you can restore to any previous state.

♻️ Crash self-healing · 3-layer keepaliveA parent–child Guardian process supervises the app and auto-restarts it with exponential backoff (1s → 3s → 9s → 15s → 30s) on unexpected exit; after 5 consecutive crashes it snapshots the config, runs an LLM self-diagnosis and attempts automatic remediation — crash history is browsable under Settings → Crash History. Once server install registers the daemon, launchd KeepAlive / systemd Restart=on-failure add an OS-level second layer — even if the Guardian itself is kill -9'd, the OS brings it back. Cron, IM channels and MCP connections each run their own watchdogs with auto-reconnect.



> For the full list of built-in features, see [CHANGELOG.md](CHANGELOG.md).



## Quick Start



### Install Locally



> 📦 Full installer list across platforms: [Releases](https://github.com/shiwenwen/hope-agent/releases)



#### macOS



##### Homebrew (recommended)



```bash

brew tap shiwenwen/hope-agent

brew install --cask hope-agent

```



> Already have `Hope Agent.app` installed manually? Append `--adopt` to let the cask take over your existing same-version app without re-downloading, or `--force` to overwrite.



##### Manual install (DMG)



Download `Hope.Agent_*.dmg` from [Releases](https://github.com/shiwenwen/hope-agent/releases) and drag into Applications.



> If macOS reports "damaged" or "cannot verify the developer" on first launch, run in Terminal:

>

> ```bash

> sudo xattr -cr /Applications/Hope\ Agent.app

> sudo codesign --force --deep --sign - /Applications/Hope\ Agent.app

> ```



Native builds for both Apple Silicon (arm64) and Intel (x64); Homebrew and manual download both pick the correct DMG for your hardware automatically.



##### Launch modes



- **Desktop GUI**: Launchpad / Applications folder (click the Hope Agent icon), or `open -a "Hope Agent"` / `hope-agent` from a terminal

- **Headless server (HTTP/WS daemon)**: `hope-agent server start`

- **ACP (IDE integration)**: `hope-agent acp`



#### Windows



##### Scoop (recommended)



```powershell

scoop bucket add hope-agent https://github.com/shiwenwen/scoop-hope-agent

scoop install hope-agent

```



##### Manual install (installer)



Download `Hope.Agent_*-setup.exe` from [Releases](https://github.com/shiwenwen/hope-agent/releases) and double-click. **Windows is not yet fully tested** — please file issues if anything breaks.



> If Windows reports "MSVCP140_1.dll was not found" or a similar missing `VCRUNTIME140.dll` / `MSVCP140.dll` error on launch, install the [Microsoft Visual C++ 2015–2022 Redistributable (x64)](https://aka.ms/vs/17/release/vc_redist.x64.exe) and relaunch.



x64 only.



##### Launch modes



- **Desktop GUI**: click "Hope Agent" in the Start menu, or `hope-agent` from PowerShell

- **Headless server (HTTP/WS daemon)**: `hope-agent server start` (PowerShell / cmd)

- **ACP (IDE integration)**: `hope-agent acp`



#### Linux



##### Arch Linux / Manjaro (AUR)



```bash

yay -S hope-agent-bin   # or paru / any AUR helper

```



Pre-built binary package (repackaged from the GitHub Release `.deb`) — no source compilation.



##### Debian / Ubuntu (apt)



```bash

curl -fsSL https://shiwenwen.github.io/hope-agent-linux-repo/pubkey.gpg | \

  sudo gpg --dearmor -o /usr/share/keyrings/hope-agent.gpg

echo "deb [signed-by=/usr/share/keyrings/hope-agent.gpg] https://shiwenwen.github.io/hope-agent-linux-repo/apt stable main" | \

  sudo tee /etc/apt/sources.list.d/hope-agent.list

sudo apt update

sudo apt install hope-agent

```



##### Fedora / RHEL / CentOS (dnf / yum)



```bash

sudo curl -fsSL https://shiwenwen.github.io/hope-agent-linux-repo/rpm/hope-agent.repo \

  -o /etc/yum.repos.d/hope-agent.repo

sudo dnf install hope-agent     # or `sudo yum install hope-agent`

```



> The older `sudo dnf config-manager --add-repo …` form has been removed in dnf5 (Fedora 41+); the `curl` variant above works on dnf4 / dnf5 / yum / zypper alike.



openSUSE users:



```bash

sudo zypper addrepo https://shiwenwen.github.io/hope-agent-linux-repo/rpm/hope-agent.repo

sudo zypper install hope-agent

```



##### Manual install (AppImage / deb / rpm)



From [Releases](https://github.com/shiwenwen/hope-agent/releases) (filenames include the arch suffix — pick `_amd64` / `_arm64` for deb/AppImage or `.x86_64` / `.aarch64` for rpm):



- AppImage: `Hope.Agent_*.AppImage` — `chmod +x` and run

- Debian / Ubuntu: `Hope.Agent_*.deb` — `sudo dpkg -i Hope.Agent_*.deb`

- Fedora / RHEL: `Hope.Agent_*.rpm` — `sudo rpm -i Hope.Agent_*.rpm`



Both amd64 (x86_64) and arm64 (aarch64) native builds are published, covering desktops, Raspberry Pi 4/5, Apple Silicon Macs running Asahi Linux, and Graviton / Ampere cloud VMs. apt and dnf automatically pick the right arch via `dpkg --print-architecture` / `$basearch`.



##### Launch modes



- **Desktop GUI**: click "Hope Agent" in your app menu, or `hope-agent` from a terminal

- **Headless server (HTTP/WS daemon)**: `hope-agent server start`

- **ACP (IDE integration)**: `hope-agent acp`



#### First launch & auto-update



1. First launch wizard: **pick a provider template → paste API key / sign in with Codex OAuth → chat.**

2. Desktop builds ship with the GitHub Releases auto-updater. Go to **Settings → About** in-app to check for and install updates, or just tell the model "upgrade" / "check for updates" in chat.

3. Versions installed via Homebrew / AUR / Scoop also receive updates through the built-in updater; the package manager's recorded version stays pinned to the initial install version and does not affect functionality.



### Self-hosting (Docker)



For running Hope Agent on a home NAS / VPS / homelab and accessing the Web GUI from a browser:



```bash

docker run -d \

  --name hope-agent \

  -p 127.0.0.1:8420:8420 \

  -v hope-data:/data \

  ghcr.io/shiwenwen/hope-agent:latest

```



Once the container is running, open  in a browser and follow the onboarding wizard to configure provider API keys. The image covers `linux/amd64` + `linux/arm64` (including Apple Silicon and Raspberry Pi) and is auto-built on every release tag.



For docker-compose, the optional Ollama sidecar for local LLMs, LAN exposure, reverse proxy + TLS, and upgrade flow, see [`docs/deployment/docker.en.md`](docs/deployment/docker.en.md).



### For developers



```bash

git clone https://github.com/shiwenwen/hope-agent.git

cd hope-agent

pnpm install

pnpm tauri dev         # desktop dev (frontend + Rust hot reload)



# Other useful commands

pnpm typecheck         # frontend typecheck (tsc -b)

pnpm lint              # lint

pnpm tauri build       # production build

```



For local Web GUI development with live reload, run `pnpm tauri dev` and open `http://localhost:1420` in your browser. That is the Vite dev server, sharing the same frontend HMR as the Tauri window. `http://localhost:8420` is the embedded HTTP/WS server's static Web GUI entry, served from `dist/` / the embedded bundle, so it behaves like the packaged browser entry and does not HMR with source changes. If your local server has an API key enabled, the `1420` page may get 401s from `8420`; for development, temporarily clear the Server API Key in Settings and restart.



## Run Modes



| Mode             | How to start                                                                      | When to use                                                                       |

| ---------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |

| Desktop GUI      | Double-click the app / `pnpm tauri dev`                                        | The most complete entry point: full GUI plus an embedded HTTP/WS server, so the desktop can serve remote clients while you use it |

| Server + Web GUI (HTTP/WS) | `server start` subcommand; `server install` registers a launchd / systemd service | Headless always-on daemon for IM channels and cron jobs; **the React frontend is `rust-embed`-baked into the server binary, so opening `http://:port` in any browser gives you the full Web GUI** — phone, tablet, any computer can connect directly without installing a client |

| ACP (stdio)      | `acp` subcommand                                                                  | IDE integration — any ACP-capable editor can call Hope Agent as its agent backend |



All three modes share the same `ha-core` core. Config, sessions, and memories live under `~/.hope-agent/`.



## Ecosystem



  📦 Model providers

  

    39 templates · 206 preset models


    International · Anthropic · OpenAI · Codex · Google Gemini · OpenRouter · Azure OpenAI · Groq · Together AI · Fireworks · Perplexity · xAI Grok · Mistral · Cohere


    China · DeepSeek · Moonshot (Kimi) · Qwen · Doubao (Volcengine) · Z.AI (GLM) · MiniMax · Xiaomi MiMo


    Local · Ollama · any OpenAI-compatible endpoint

  



  💬 IM channels

  12 · Telegram · Discord · Slack · Feishu · Google Chat · LINE · QQ Bot · Signal · iMessage · IRC · WeChat · WhatsApp



  🌐 UI languages

  12 · Simplified Chinese · Traditional Chinese · English · Japanese · Korean · Spanish · Portuguese · Russian · Arabic · Turkish · Vietnamese · Malay



## Project Structure



Cargo workspace, three crates; all business logic lives in `ha-core`:



```

crates/

  ha-core/       Rust core library (zero Tauri deps) — where the logic lives

  ha-server/     axum HTTP/WS daemon (thin shell)

src-tauri/       Tauri desktop shell (thin shell)

src/             React 19 + TypeScript frontend

skills/          Bundled skills (ship with the app)

```



For the full module map, architecture conventions, and coding guidelines, see [AGENTS.md](AGENTS.md).



## Documentation



See [docs/](docs/).



## Contributing



The main branch is under active development — issues and PRs are welcome. Please skim the **Architecture** and **Coding Conventions** sections of [AGENTS.md](AGENTS.md) before contributing.



Common commands:



```bash

pnpm tauri dev                    # desktop dev

cargo check --workspace              # Rust dep / type check

cargo test -p ha-core -p ha-server   # core tests

node scripts/sync-i18n.mjs --check   # i18n completeness check

```



## Community



- 🐛 [Issues](https://github.com/shiwenwen/hope-agent/issues) — bug reports, feature requests

- 💡 [Discussions](https://github.com/shiwenwen/hope-agent/discussions) — usage, ideas, Q&A

- ⭐ If Hope Agent helps you, consider giving it a star on GitHub

- 📮 Roadmap, a dedicated docs site, and more community channels are on the way



## Acknowledgements



- [openclaw](https://github.com/openclaw/openclaw) — inspiration in the local AI assistant space

- [Ollama](https://ollama.com/) — the one-click local LLM experience is built on top of Ollama's local runtime and its OpenAI-compatible endpoint; Hope Agent only wraps the GUI layer, while Qwen / Gemma and other models are distributed through the Ollama model library

- [ClawHub](https://www.clawhub.com/) / [SkillHub](https://skillhub.cn/) — public skill discovery sources for Hope Agent

- [Hermes Agent](https://github.com/NousResearch/hermes) (originally adapted from [obra/superpowers](https://github.com/obra/superpowers)) — several bundled coding-methodology skills are vendored from here (MIT); see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)

- [Tauri](https://tauri.app/), [axum](https://github.com/tokio-rs/axum), [React](https://react.dev/), [shadcn/ui](https://ui.shadcn.com/), [Streamdown](https://github.com/streamdown/streamdown), [Radix UI](https://www.radix-ui.com/), and the rest of the open source stack Hope Agent stands on

- Everyone who has filed issues, tested builds, and given feedback along the way



## Star History





  

    

    

    Star History Chart

  




## License



[MIT](LICENSE)