Keep work moving across chat turns, restarts, subagents, and paired machines.
MintClaw is a Go-native personal agent runtime for workflows that need to stay understandable and recoverable after the current chat turn ends. Connect the models, chat apps, MCP servers, and skills you already use; delegate work to durable background tasks; steer an active run; pause for an authorized human; and extend execution to explicitly paired machines.
- Work that survives interruption. Async tasks, inbound work, user interactions, session goals, and remote-node operations have explicit persisted state and restart behavior.
- Control while the agent is working. Steering lets a newer message change direction between tool calls, with undispatched side effects skipped safely and represented in model context.
- Human checkpoints without holding the process open. A foreground turn or background task can pause for authorized input or approval and resume the exact call after an answer—even across a restart.
- Compositional multi-agent workflows. Spawned and delegated work has durable status, bounded delivery destinations, model policy, and parent/user handoff semantics.
- Remote execution with explicit authority. The slim
mintclaw-nodecompanion pairs over WSS and is constrained by both gateway and node-local policy, with approval and no-blind-replay behavior for uncertain operations. - Open extension surfaces. Use built-in tools, MCP servers, workspace skills, provider routing, scheduled jobs, chat channels, the CLI, or the Web launcher without tying the runtime to one model vendor.
MintClaw is a downstream fork of PicoClaw. It keeps the practical Go foundation while intentionally diverging around workflow durability, delivery ownership, multi-agent control, context management, and operations. Treat MintClaw as its own runtime rather than as a drop-in PicoClaw build.
PicoClaw remains the better starting point when staying close to upstream and targeting the smallest practical hardware are the main priorities. MintClaw accepts a larger operational surface in exchange for explicit contracts around long-running work, human decisions, restart recovery, and paired machines.
Read MintClaw and PicoClaw for the fork relationship, the intentional divergence, and the trade-offs behind it.
Prerequisites: Go 1.26+. Node.js 22+ and pnpm 10.33.0+ are needed only for the Web launcher.
git clone https://github.com/bogdanovich/mintclaw.git
cd mintclaw
make deps
make build
./build/mintclaw onboard
./build/mintclaw agent -m "What should we automate first?"onboard creates the local configuration and workspace. Add a provider key,
then use interactive CLI mode with ./build/mintclaw agent or start chat-app
integrations with ./build/mintclaw gateway.
(cd web/frontend && pnpm install --frozen-lockfile)
make build-launcher
./build/mintclaw-launcher
# Open http://localhost:18800The first visit creates a dashboard password. Do not expose the launcher to an untrusted network; see the Web launcher security notes.
Prefer containers? Follow the Docker and launcher guide. Running on an older Android phone? Use the Termux guide.
Caution
MintClaw is under rapid development and may contain unresolved security
issues. Review sender allowlists and tool policies, keep the launcher private,
and run mintclaw doctor --strict before exposing a deployment. Do not treat a
pre-1.0 build as a hardened multi-user service.
- An always-on assistant reached through Telegram, Discord, WhatsApp, Slack, Matrix, and other supported chat apps.
- A personal operations agent that schedules work, delegates long tasks, asks for decisions, and reports completion to the right conversation.
- A model-agnostic tool host using local tools, web search, MCP servers, and installable workspace skills.
- A small multi-machine setup where a central gateway invokes only approved capabilities on paired Linux or macOS nodes.
- A context-aware assistant using Seahorse-backed history, bounded prompt assembly, session routing, and durable per-conversation goals.
| Surface | Best for | Start here |
|---|---|---|
| CLI | One-shot work, interactive chat, scripting, and diagnostics | mintclaw onboard, mintclaw agent, mintclaw doctor |
| Web launcher | Browser-based setup, configuration, and chat | Docker and launcher guide |
| Gateway | Always-on chat apps, scheduled work, and live agent sessions | Chat apps |
| Docker | Reproducible server or local deployment | Docker Compose |
| Android / Termux | Reuse an ARM64 phone as a small always-on host | Android Termux guide |
| Node companion | Add policy-constrained execution on another machine | Node companion guide |
The README stays intentionally high level. Detailed provider lists, channel setup, tool configuration, and CLI behavior live in the documentation.
| Need | Documentation |
|---|---|
| Install and configure | Docker and quick start · Configuration |
| Connect models and chat apps | Providers and models · Chat apps |
| Run durable workflows | Spawn and async tasks · Human interaction · Cron |
| Extend the runtime | Tools · MCP CLI · Node companion |
| Understand behavior | Architecture · Sessions · Steering |
| Operate safely | Doctor · Security · Troubleshooting |
The full documentation index is at docs/README.md.
Contributions are welcome. Start with CONTRIBUTING.md for the local development workflow and validation requirements.
MintClaw is available under the MIT License.