English · 简体中文 · Documentation
A macOS installer is available. Download the DMG, with no build tools needed. This download is not notarized by Apple; see the first-open instructions below.
Clumsies helps teams maintain shared Markdown guidance for coding agents: architecture decisions, project constraints, and procedures. The organization keeps published Memory; each Project selects the Memory it uses and connects it to local repositories. Agents retrieve relevant guidance while they work and can propose changes when a user asks.
The macOS dashboard brings together memory growth, retrieval activity, and coverage.
The quickstart follows one workflow:
- Create a Project and bind your working repository.
- Select the Memory that Project needs from the organization.
- Work in Codex with the Clumsies integration enabled; it retrieves relevant Memory as part of the task.
- Explicitly ask Codex to update Memory when a rule or procedure needs to change.
- Inspect the resulting Draft in Clumsies and submit a Review. An organization owner or administrator approves and publishes it.
Retrieval does not automatically rewrite Memory. A saved Draft is a proposal, and publication requires human review. Drafts can affect that Project's local Memory view before publication.
Supports macOS 14 or later on Apple Silicon Macs (M1 or newer). No Xcode, Rust, or other build tools are needed to install the DMG.
- Open GitHub Releases and download
Clumsies-*-macos-arm64.dmgfrom the Latest release. - Open the DMG, drag Clumsies.app into Applications, eject the disk image, and open the installed App.
- This download is not notarized by Apple. If macOS blocks the first launch, confirm the file came from this repository, then use System Settings → Privacy & Security → Open Anyway. Managed Macs may restrict this exception. Apple's instructions
- Keep the default Server address
https://app.clumsies.aiand sign in with an account admitted by that organization. Use your team's Server address for another deployment.
Continue with the quickstart to connect your organization, create a Project, and connect your agent. To update manually, quit the App, download a newer DMG, and replace the existing application; accounts, Memory, and settings are retained.
If you previously installed ~/Applications/Clumsies.app, quit it and replace it there to avoid keeping two copies. For source installation, see the source installation guide.
Install Clumsies from:
https://github.com/lilhammerfun/clumsies/releases/latest
Download the DMG from the Latest release and install its
Clumsies.app in Applications. If already installed, quit it and replace it
in its existing location. Preserve accounts, Memory, and settings.
Use the built-in Server address. Do not create a Dev Instance or start a
local Server. Tell me when macOS first-open approval or sign-in needs me.
Then guide me through the Clumsies quickstart to connect my organization,
create a Project, and connect my agent.
For Windows/Linux, use the CLI installation and Review workflow. The CLI workflow produces a Linux user package, Windows user installer, and portable ZIP; upcoming tagged releases include them. The native macOS App also embeds the human CLI.
Windows/Linux desktop development is paused; its source, GUI packages, and dedicated workflows have been removed from the active tree. Earlier implementations remain available in Git history. Contributions for these platforms must target the CLI, clumsiesd, Agent/MCP integration, or their installation and distribution. Desktop fixes and features resume only when a maintainer takes responsibility for ongoing platform testing, packaging, releases, and compatibility.
Clumsies includes integrations for the macOS Codex App, Claude Code, opencode, DeepSeek Harness (dsh), and Google Antigravity. Install the agent host separately. Adapters are configured once per Mac user for all projects; Codex is selected by default during first-time setup. Repository bindings determine which Project's Memory an agent can use.
After changing the Codex integration, restart Codex and start a new task. Retrieval needs the local daemon and a ready index; first use downloads the retrieval models. Host-specific requirements are documented in Agent integration.
Teams can deploy the Rust Server and PostgreSQL with their own OIDC identity provider. See organization deployment.
Overview · Architecture · Data model · Domain interfaces · Development workflow
MIT © 2026 Clumsies Lab