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 · Pursues goals autonomously · Orchestrates work dynamically · Reachable from every chat app you use

English · 简体中文 · Website

Watch Hope Agent in 3 minutes

English narration and captions. Explore goals, tools, memory, knowledge, and design in one desktop workflow.

https://github.com/user-attachments/assets/e1728465-0f5b-47a6-8af8-b9806067a6b4

Product presentation built with real Hope Agent components and fixed demo data.

From a project brief to three deliverable drafts — with project history and session status in view.

1920×1080 screenshots of the running Web GUI. Projects, sidebar entries, and notes use demo content; deliverables come from actual runs. Dashboard metrics use illustrative sample data.

Hope Agent is a local-first, desktop-first personal AI agent that can also run continuously as a service. It opens like mature desktop software while offering real agentic capability: understanding long-term context, using tools to complete work, and reliably pursuing goals even after you step away.

Hope Agent did not begin after “desktop AI agents” became a popular category. We started building it when desktop agents were still uncommon and Codex itself was in an earlier form. We have always focused on the product itself, not on manufacturing attention. As more products have moved in the same direction, they have reinforced our original conviction: AI assistants will move beyond the chat box and become personal software people can trust with long-running work.

Contents

• Core Capabilities
• Capability Overview
• Quick Start
  • Install Locally
  • Self-hosting (Docker)
  • For developers
• Run Modes
• Ecosystem
• Project Structure
• Documentation
• Contributing
• Community
• Acknowledgements
• Star History
• License

Core Capabilities

🖥️ A desktop agent that just works

A native GUI, a broad set of provider templates and preset models, and one-click local model setup. Paste an API key or sign in—no runtime setup, CLI learning curve, or config sprawl required.

🧭 Completes work, not just replies

Goal defines the outcome, Workflow dynamically organizes execution, and Loop decides when to continue. Complex work can progress in the background while remaining visible, pausable, resumable, and adjustable.

🧠 Long-term memory and knowledge

Cross-session memory, on-demand recall, offline consolidation, user profiles, and reusable skills compound over time. Knowledge Space lets you and the AI read and write real Markdown together as a traceable second brain.

🎨 From an idea to a deliverable design

Design Space turns a prompt or reference image into 10+ artifact types, including websites, mobile prototypes, and presentations, with visual editing, version history, multi-format export, and handoff into a real codebase.

🛠️ Acts in the real environment

With permission and approval, Hope Agent can control the computer and browser, run commands, edit files, call MCP tools, connect to workspaces, and coordinate multiple agents.

🌐 Handoff across devices, always available

Desktop / Server / Web / ACP share the same core. The same session, memory, and task state can continue across desktop, browser, and popular IM channels.

🛡️ Local-first, controlled, dependable

Data stays local by default and model requests go directly to providers. Tool approvals, Docker sandboxing, configuration rollback, crash recovery, and keepalive layers protect long-running operation.

Capability Overview

🎨 Design & knowledge

🎨 Design Space

Generate websites, mobile prototypes, presentations, dashboards, posters, documents, email, images, motion, audio, and interactive components from a prompt or reference image. Generation streams into a live preview; each project includes AI chat, element-level editing, annotations, undo / redo, device previews, version history, an artifact library, and HTML / PNG / PDF / PPTX / MP4 / ZIP export.

🧩 Design system to code

Extract a brand system from screenshots, URLs, Figma, or an existing repository, reuse it across artifacts, and export multi-platform design tokens or a code handoff package. Bind a design project to a real repository, send an artifact to the main conversation for implementation, and surface later code changes back in the design.

🧠 Knowledge Space · second brain

You and the AI work on the same real Markdown notes, with source archiving, full-text and vector retrieval, backlinks, graph view, atomic notes, and reviewable AI organization proposals. Existing Obsidian vaults can be attached, external changes sync live, and source Evidence remains traceable.

Design Space · A generated landing page with an editorial hero, product illustration, feature sections, and a call to action.

Knowledge Space · Nine connected Markdown notes inform an AI creative brief, with the source note and response side by side.

🧭 Long-running work & autonomy

🎯 Goal · keep pursuing the outcome

Give Hope Agent an outcome and completion criteria, and it keeps decomposing, executing, checking, and advancing. Goals support budgets, progress, pause, and resume; completion requires a conservative audit with result evidence.

🧩 Workflow · dynamic orchestration

The model organizes phases, conditions, parallel work, multiple agents, tools, diffs, reviews, and verification when the task benefits from it. Every run has a durable trace with pause, resume, cancel, and conservative restart recovery.

🔁 Loop · continue on time or events

Continue on fixed intervals, conditions, internal events, or model-selected wakeups. Each iteration can resume the current conversation or launch a Goal-bound Workflow, with budgets, backoff, and no-progress protection.

📋 Plan, Task, and background work

Complex work can start with an editable plan while Tasks expose live progress. Long-running tools and sub-agents run in the background, and milestones return progressively to the main conversation without blocking the chat.

Mental model: Goal defines the outcome, Workflow performs one concrete execution, Loop decides when to advance again, Task exposes current progress, and Mode controls execution autonomy. They compose cleanly but can also be used independently.

🧠 Memory & growth

🧠 Persistent cross-session memory

Memory is organized across Global, Project, and Agent scopes. A compact Core stays stable in context while detailed content returns on demand through full-text and vector retrieval instead of being resent every turn.

🔍 Recall, consolidation, and reflection

The model can recall memory when a task needs it, and users can enable Fast or Deep Recall. Idle-time consolidation produces a Dream Diary and can distill reviewable communication preferences, work habits, and long-term patterns from history.

🛠 Skills that grow

Complex work can become a draft skill for your review and later reuse. Skills support conditional activation, sub-agent execution, tool allowlists, and the agentskills.io standard.

💾 Long conversations and incognito mode

Progressive context compaction preserves key facts and tool-call relationships across long conversations. Incognito sessions disable long-term memory, cross-session awareness, and persistence paths, then remove the session data when the conversation ends.

🛠 Tools & connections

🖱️ Computer and browser control

On macOS, granted permissions let Hope Agent observe and operate the desktop, windows, menus, keyboard, and pointer. The controllable browser includes a live mirror so you can see the pages the Agent is visiting and manipulating. Side effects share one approval flow.

👥 Multiple agents and natural-language scheduling

Preset teams or dynamic sub-agents work in parallel and summarize results back to the main conversation. Natural-language schedules can run recurring work and deliver results to a chosen IM channel.

📁 Project containers

Keep related sessions, project instructions, memory, and shared files together. Uploaded files are extracted automatically and exposed as a directory, inline context, or on-demand reads according to size.

🔌 MCP and Hooks

The built-in MCP client covers major transports and OAuth 2.1. Hooks attach command / HTTP / MCP / prompt / agent handlers to 20+ lifecycle events, with layered configuration and hot reload.

🔧 Toolbox and workspaces

Built-ins include AI image and audio generation (speech, music, and sound effects), web search, bash, file operations, Canvas, URL preview, and self-diagnosis. Deep Feishu / Lark integration adds 40+ tools across documents, bitable, drive, wiki, approvals, calendar, contacts, and recruiting.

📊 Dashboard + Recap

Track cost, tokens, activity, health, Plans, and long-running work in one place. Recap reviews a period of conversation history, produces a multi-section report, and exports standalone HTML.

Dashboard · Insights · A 30-day view of usage, cost, health, and activity, with comparisons to the previous period. Metrics use illustrative demo data.

🌐 Desktop, service & cross-device

🖥️ Native GUI and model setup

macOS provides the complete desktop experience, while Linux and Windows support is currently experimental. The interface is multilingual, with broad provider coverage, a large preset model catalog, and automatic rotation across multiple API keys per provider.

🦙 One-click local models

No account, API key, or terminal required. Pick a model that fits your hardware and Hope Agent handles Ollama installation, model download, provider registration, and switching; local embedding models use the same flow.

🤝 IM channels and session handoff

Connect Telegram, Discord, Slack, Feishu, and other popular IM channels. Images, voice, and files become multimodal context; sessions hand off between desktop, browser, and IM, and active responses can live-mirror into chat apps.

🌐 Standalone service and multiple run modes

hope-agent server stays online on a NAS, home server, or cloud VM with a full embedded Web GUI. hope-agent acp serves as an Agent backend for IDEs. Every entry point shares the same core, sessions, memory, and configuration.

🛡 Security & reliability

🔒 Tool approval + Docker sandbox

Sensitive tool calls enter a unified approval flow. High-risk commands and file writes can run inside a Docker sandbox to reduce the blast radius of privileged mistakes.

🏠 Local-first · zero third-party hops

Configuration, sessions, memory, attachments, skills, and logs live under ~/.hope-agent/ by default, while API keys connect directly to model providers. Daemon mode adds Bearer token authentication and SSRF protection policies.

🛟 Rollback, recovery, and keepalive

Configuration changes create local snapshots for one-click rollback. Guardian, system services, and subsystem watchdogs provide restart, diagnosis, and reconnection so long-running work recovers in an observable way.

For the complete version history, see CHANGELOG.md. Implementation details live under docs/architecture/.

Quick Start

Install Locally

📦 Full installer list across platforms: Releases

🌏 Can't reach GitHub? Every installer is mirrored at (Cloudflare R2, the same domain as the apt / dnf repos), and each manual-install entry below links the mirror directly. The desktop auto-updater prefers this mirror too, with GitHub as the fallback. Past versions are kept indefinitely under https://repo.hopeagent.ai/download/v/.

macOS

Homebrew (recommended)

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 and drag into Applications. Mirror: Hope.Agent_aarch64.dmg.

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

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

Regular releases provide native Apple Silicon (arm64) builds. Intel Mac (x64) packages are produced separately on demand: check that the target release actually contains an x64 DMG before installing. Homebrew and the download page cannot supply an Intel package when that asset is absent.

Launch modes

• Desktop GUI: Launchpad / Applications folder (click the Hope Agent icon), or open -a "Hope Agent" / hope-agent from a terminal
• Browser Web GUI: open after launching the desktop app, or run hope-agent server start to start only the service without a desktop window
• ACP (IDE integration): hope-agent acp

Windows

Scoop (recommended)

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 and double-click. Mirror: Hope.Agent_x64-setup.exe. 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) and relaunch.

x64 only.

Launch modes

• Desktop GUI: click "Hope Agent" in the Start menu, or hope-agent from PowerShell
• Browser Web GUI: open after launching the desktop app, or run hope-agent server start in PowerShell / cmd to start only the service without a desktop window
• ACP (IDE integration): hope-agent acp

Linux

Arch Linux / Manjaro (AUR)

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)

curl -fsSL https://repo.hopeagent.ai/pubkey.gpg | \
  sudo gpg --dearmor -o /usr/share/keyrings/hope-agent.gpg
echo "deb [signed-by=/usr/share/keyrings/hope-agent.gpg] https://repo.hopeagent.ai/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)

sudo curl -fsSL https://repo.hopeagent.ai/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:

sudo zypper addrepo https://repo.hopeagent.ai/rpm/hope-agent.repo
sudo zypper install hope-agent

Manual install (AppImage / deb / rpm)

From 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. Mirror: amd64 · aarch64
• Debian / Ubuntu: Hope.Agent_*.deb — sudo dpkg -i Hope.Agent_*.deb. Mirror: amd64 · arm64
• Fedora / RHEL: Hope.Agent_*.rpm — sudo rpm -i Hope.Agent_*.rpm. Mirror: x86_64 · aarch64

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
• Browser Web GUI: open after launching the desktop app, or run hope-agent server start to start only the service without a desktop window
• 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 a built-in auto-updater (it reads the repo.hopeagent.ai mirror first and falls back to GitHub Releases). Go to Settings → About in-app to check for and install updates, or just tell the model "upgrade" / "check for updates" in chat. Installers fetched by the updater are signature-verified against the built-in public key — the mirror and GitHub go through the identical check. (Manual downloads are installed by your OS and do not pass through it.)
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.

To connect from a phone or another computer, set an API key under Settings → Server and change the bind address to 0.0.0.0:8420. After restarting, open http://:8420. Never expose the port to a LAN or the public internet without authentication; for public access, put it behind an HTTPS reverse proxy. See the Docker deployment guide.

Self-hosting (Docker)

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

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.

For developers

git clone https://github.com/shiwenwen/hope-agent.git
cd hope-agent
pnpm install
pnpm dev:desktop       # default desktop dev (frontend + Rust hot reload)

# Other useful commands
pnpm typecheck         # frontend typecheck (tsc -b)
pnpm lint              # lint
pnpm tauri build       # production build

Desktop development enables extra binaries only when they are needed, so ordinary UI and business-logic work does not wait for unrelated Rust crates:

The default command delegates to pnpm exec tauri dev --config src-tauri/tauri.dev.conf.json. Prefer the scripts above so startup flags and optional-component conventions stay aligned. Production pnpm tauri build still builds and bundles both the Browser Host and Eval Sidecar.

For local Web GUI development with live reload, run pnpm dev:desktop 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

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

Ecosystem

📦 Model providers

About 50 templates · Several hundred preset models  

International · Anthropic · OpenAI · Codex · GitHub Copilot · Google Gemini · OpenRouter · Requesty · Azure OpenAI · Groq · Together AI · Fireworks · Novita · 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

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

🌐 UI languages

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

Project Structure

Layered multi-crate Cargo workspace: kernel capabilities live in ha-core; self-contained feature domains live in feature crates (ha-acp / ha-browser / ha-design / ha-mac / ha-mcp / ha-media / ha-pet / ha-updater / ha-vcs / ha-weather, with more moving out as the split continues):

crates/
  ha-base/           Infrastructure foundation (paths / logging / platform / security)
  ha-config-schema/  AppConfig wire types (pure data definitions)
  ha-core/           Rust core library (zero Tauri deps) — kernel + most business logic
  ha-acp/            ACP feature crate (stdio server mode + external agent control plane)
  ha-browser/        Browser feature crate (extension backend / CDP / browser tool)
  ha-design/         Design space feature crate (artifacts store + compile/export + 3 tools)
  ha-mac/            macOS control feature crate (Accessibility / screenshot / mac_control tool)
  ha-mcp/            MCP client feature crate (McpManager / transports / OAuth / two tools)
  ha-media/          Media feature crate (image/audio generation adapters + STT engines + two tools)
  ha-pet/            Desktop pet feature crate (sprite store / import / creator / activity projection)
  ha-updater/        Self-update feature crate (depends on ha-core, wired by shells)
  ha-vcs/            VCS & local-exec feature crate (git control-plane ops + Docker sandbox machinery + SearXNG deploy)
  ha-weather/        Weather feature crate (depends on ha-core, wired by shells)
  ha-server/         axum HTTP/WS daemon (thin shell)
  ha-browser-host/   Browser helper process
  ha-eval-spec/      Evaluation protocol (no ha-core dependency)
  ha-eval/           Evaluation CLI
src-tauri/       Tauri desktop shell (thin shell)
src/             React 19 + TypeScript frontend
skills/          Bundled skills (ship with the app)

For constraints across modules and development entry points, see AGENTS.md. Module designs are in the technical documentation index.

Documentation

• 📖 User Guide — the complete user manual: installation, getting started, and how to use and configure every feature (简体中文)
• 🏗️ Technical docs — architecture and implementation details (for developers)

Contributing

The main branch is under active development — issues and PRs are welcome. Before contributing, read the global constraints in AGENTS.md, then follow the documents relevant to your changes. Frontend conventions are in src/AGENTS.md.

Common commands:

pnpm dev:desktop                  # default desktop dev
cargo check --workspace              # Rust dep / type check
cargo test -p ha-base -p ha-config-schema -p ha-core -p ha-acp -p ha-browser -p ha-design -p ha-mac -p ha-mcp -p ha-media -p ha-pet -p ha-updater -p ha-vcs -p ha-weather -p ha-server   # core tests
node scripts/sync-i18n.mjs --check   # i18n completeness check

Community

• 🐛 Issues — bug reports, feature requests
• 💡 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

• Ollama — 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 / SkillHub — public skill discovery sources for Hope Agent
• Tauri, axum, React, shadcn/ui, Streamdown, Radix UI, 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

License

MIT