OpenMozi: a hackable desktop agent OS that verifies its own work

What OpenMozi actually solves, and for whom

Most chat-based coding assistants stop at prose. You ask for a refactor, you get a diff in a text box, and you paste it yourself. OpenMozi takes the opposite position: the README describes it as "a personal AI agent that lives on your machine" that "uses your tools, works in your projects, and delivers real files, not just chat." The stated target is the developer who wants an agent with hands, pointed at a real folder, on a real git branch.

The README is unusually candid about motivation. The author writes that there is "no grand vision here" and that the goal was to build a hackable Agent OS from scratch to understand how the pieces fit together. That framing matters when you evaluate it. This is a system built by someone who wanted to see the internals, not a product team chasing an enterprise buyer. The topics list (agent, ai-agent, anthropic, claude, llm, personal-assistant, typescript) matches the audience: individual engineers and tinkerers, not platform teams.

The concrete problem it addresses is the gap between an agent that suggests work and an agent that performs it. OpenMozi runs shell commands, edits files, generates Office documents, and then checks what it claims against the filesystem. The README calls this out directly: "Every deliverable it claims is verified against the filesystem before it reports done: no fake success." If you have ever watched an agent announce a completed task while the file on disk was untouched, that sentence is the whole pitch.

The composer, the permission levels, and how a task flows

The interaction model is a single composer panel that the README calls "the cockpit." Before you type a request, you choose four things: a project (any folder or git repo), the git branch to work on, a permission level running from read-only to full access, and the model. The permission level is the real safety control here. Read-only means the agent can inspect but not mutate; full access means shell commands and file writes are in scope. That is a coarse dial compared with per-command approval prompts, and the README does not describe an approval queue, so the granularity you get is the granularity of that setting.

Branch handling is where the design shows restraint. The README states that the built-in branch switcher performs an honest git switch and that it will "never auto-stash, never force; conflicts abort with git's own message." That is a deliberate choice to fail loudly rather than silently move your uncommitted work out of the way. If you have uncommitted changes and switch branches through the UI, expect the operation to stop and hand you git's error text instead of resolving it for you.

Capabilities are grouped into six areas in the README: code, documents, research, memory, automation and skills. Memory persists across sessions, so a fact told once is expected to survive to the next week. Automation covers scheduled and recurring tasks with a dedicated UI plus reusable task templates. Skills are loaded on demand: the model sees a one-line catalog of the 25 built-in skills and pulls full instructions only when a task needs them, which keeps the prompt small until relevance is established.

Installing OpenMozi on macOS Apple Silicon

The desktop app is the primary path. The README points to GitHub Releases for the latest Apple Silicon DMG and its checksum file, and it carries a prominent warning: current macOS downloads are not signed with an Apple Developer ID and are not notarized, so Gatekeeper may report that MOZI is damaged, cannot be opened, or comes from an unidentified developer. Verify the DMG's SHA-256 against the published openmozi-<version>-SHA256SUMS.txt before removing quarantine. The README is explicit that the checksum confirms which GitHub artifact you downloaded and does not replace Apple code-signing trust.

After verifying, drag MOZI.app into /Applications, then clear the quarantine attribute on that verified copy and launch it:

xattr -dr com.apple.quarantine /Applications/MOZI.app
open -a /Applications/MOZI.app

If you would rather build from source, the README gives a three-step sequence. The setup script locates a compatible Node.js (22 LTS preferred) from Homebrew, nvm, fnm, mise, volta or asdf, and runs the repository-pinned pnpm without corepack enable, without sudo and without a global pnpm install.

git clone https://github.com/spytensor/openmozi.git
cd openmozi
./scripts/setup.sh app
# → desktop/dist/mac-arm64/MOZI.app  (drag into /Applications)

If no usable Node exists, the script prints the exact install command for your platform. Running ./scripts/setup.sh --check reports what it would use without changing anything, which is the sensible first command on a machine you care about. Requirements are Node.js >= 22.12 and < 26; the README states Node 26+ is too new for the native dependencies and Node 23 is rejected by dependency engine pins. On first launch you create a local account and add an LLM API key. The app manages its own backend and data, so there is no separate server to start.

Running OpenMozi headless and pointing it at a provider

MOZI also runs as a server with a Web UI, described as the same runtime with the same features. Supported server architectures are Linux x64/arm64 and macOS Apple Silicon. Intel Macs are explicitly unsupported because the vector database dependency does not publish a macOS x64 binary. That is a hard boundary, not a configuration problem you can work around.

Onboarding is interactive and writes server-mode configuration to ~/.mozi/mozi.json, which the README notes is JSON rather than YAML.

pnpm mozi onboard   # interactive setup: provider, API key
pnpm start          # Web UI at http://localhost:9210

You can inspect or change configuration without re-running the wizard: pnpm mozi config get brain and pnpm mozi config set brain.model <model>, or pnpm mozi onboard --update. The provider catalog lists 27 OpenAI-compatible options, with MiniMax as the default (MiniMax-M3). Keys come from environment variables such as ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, DASHSCOPE_API_KEY, MOONSHOT_API_KEY and GROQ_API_KEY, and Ollama runs fully local. Regional endpoints are handled through <PROVIDER>_BASE_URL overrides.

For container deployment, docker-compose.yml binds to 127.0.0.1:9210:9210 and the comments are blunt about why: when MOZI runs with auth_mode=none, every /api endpoint is open, so exposure should go through the nginx reverse proxy in deploy/nginx.conf.example rather than by changing the bind address. The compose file sets MOZI_HOME to /data with a single ./data mount, and MOZI_SERVER_AUTH_MODE to local, where the first account to register bootstraps as admin.

Documents, the ONLYOFFICE upgrade, and where previews stop

Document generation is the capability that separates OpenMozi from a terminal wrapper. It produces Word, PowerPoint, Excel and PDF files and previews them inside the app: docx through an embedded viewer, spreadsheets as interactive grids, slides and PDFs with full CJK text. The README states that preview quality degrades gracefully without optional extras, and that hooking up a local ONLYOFFICE container from docker-compose.yml upgrades the preview to a full editor.

The optional dependencies are worth reading carefully because they define the ceiling. LibreOffice handles slide and PDF conversion for previews. Docker plus the office profile enables editor-grade Office viewing, gated by ONLYOFFICE_JWT_SECRET. In .env.example the relevant keys are OFFICE_DOCUMENT_SERVER_URL, OFFICE_DOCUMENT_SERVER_INTERNAL_URL, OFFICE_STORAGE_BASE_URL and ONLYOFFICE_JWT_SECRET, with the comment that you generate a stable secret and then run docker compose --profile office up -d. Skip all of it and you still get generated files; you just get a viewer instead of an editor.

One deployment detail that will bite locked-down networks: the Dockerfile installs ca-certificates in the builder stage and optionally decodes a base64 PEM root certificate from the MOZI_EXTRA_CA_CERT_B64 build argument into /usr/local/share/ca-certificates. If Docker sits behind a TLS-intercepting proxy, the README's example exports that variable from a company root CA before building. The compose file repeats the warning that a certificate is public material and a private key must never go there.

The limitations the README admits, and the ones it does not

The unsigned macOS build is the most consequential limitation, and to the project's credit the README states it in a warning block rather than a footnote. Removing quarantine with xattr is a real trust decision. You are telling Gatekeeper to stop checking a binary that Apple has not verified. The checksum proves the download matches the release artifact; it says nothing about whether the artifact is safe. For a personal machine running a personal agent, that may be acceptable. For a managed fleet, it is a blocker until the project signs and notarizes.

The permission model is the second constraint. A read-only to full-access dial is simple, but there is no described mechanism for approving individual shell commands, and the README does not document rollback of agent-made changes. Branch switching refuses to stash or force, which protects your working tree, but nothing in the README describes how to undo a file edit the agent already committed to disk. Treat git as your undo, and keep the agent on a branch you are willing to discard.

The third is platform reach. Intel Macs are out because of the vector database binary, and Node 26+ is out because of native dependency compatibility. If your team standardizes on the newest Node release, you will be pinning back or using .nvmrc. And the honest self-description in the README, that this is a hackable system built to understand the internals, is also a signal about support expectations. The repository was last pushed on 2026-08-07, with v1.5.1 released on 2026-08-03; the README does not describe a support policy, a deprecation process or a long-term roadmap.

How OpenMozi differs from Claude Code and similar agent CLIs

The closest comparison is Anthropic's Claude Code, which the README gestures at by describing MOZI as "a personal, self-hosted Codex" and by noting that the built-in skills adapt the Anthropic official skill catalog. The difference in approach is the surface area and the storage model. Claude Code is a terminal-first agent tied to Anthropic's models through an Anthropic account. OpenMozi is a desktop application with a composer UI, its own local account system, and a provider catalog of 27 OpenAI-compatible endpoints, so the model is a setting rather than a dependency. You can run it against Ollama and keep inference local.

The second difference is artifact handling. A terminal agent returns text and diffs to your shell. OpenMozi generates Word, PowerPoint, Excel and PDF files and renders them in-app, with an optional ONLYOFFICE container for editing. If your work product is a report or a deck rather than a commit, that is a different kind of tool.

The third is the extension point. Skills load on demand from a one-line catalog, and the README says you can add your own by dropping a SKILL.md into your workspace. That is a lower ceremony than writing a plugin against a host API, and it fits the hackable framing. Where Claude Code wins is distribution trust: it does not ask you to strip a quarantine flag. If your organization requires signed, notarized binaries, OpenMozi is the wrong choice today regardless of features.

Editorial conclusion

Adopt OpenMozi if you want a local, MIT-licensed agent that edits real repositories and produces Word, PowerPoint, Excel and PDF artifacts without a hosted backend, and you accept that macOS builds are unsigned. Do not adopt it if you need Intel Mac support, a signed and notarized installer, or a documented rollback path for agent-made changes. Before trusting it on a work repo, verify the DMG SHA-256 against the published openmozi-<version>-SHA256SUMS.txt, run ./scripts/setup.sh --check to confirm which Node and pnpm the build will use, and try the branch switcher on a scratch clone to see how it behaves when git switch conflicts.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. spytensor/openmozi on GitHub