README
¶
A durable, operator-controlled agent runtime for personal automation
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.
Why MintClaw
- 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.
From PicoClaw to MintClaw
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.
Quick start
Build the CLI
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.
Launch the Web console
(cd web/frontend && pnpm install --frozen-lockfile)
make build-launcher
./build/mintclaw-launcher
# Open http://localhost:18800
The 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 --strictbefore exposing a deployment. Do not treat a pre-1.0 build as a hardened multi-user service.
What you can build
- 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.
Run it your way
| 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 |
Documentation
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.
Contributing
Contributions are welcome. Start with CONTRIBUTING.md for the local development workflow and validation requirements.
MintClaw is available under the MIT License.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var OnboardWorkspace embed.FS
OnboardWorkspace embeds the default onboarding workspace template.
Keeping this embed at the module root lets us source files directly from the tracked `workspace/` tree, instead of relying on a generated copy inside `cmd/...` that may be absent in clean checkouts and CI lint runs.
Functions ¶
This section is empty.
Types ¶
This section is empty.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
membench
command
|
|
|
mintclaw
command
|
|
|
mintclaw-node
command
|
|
|
mintclaw-node-broker
command
|
|
|
mintclaw-node-coordinator
command
|
|
|
mintclaw-node-file-helper
command
|
|
|
mintclaw-node-release
command
|
|
|
mintclaw-node-service-helper
command
|
|
|
mintclaw/internal/cliui
Package cliui renders human-oriented CLI output: bordered panels and columns on wide interactive terminals.
|
Package cliui renders human-oriented CLI output: bordered panels and columns on wide interactive terminals. |
|
examples
|
|
|
mintclaw-echo-server
command
mintclaw-echo-server is a minimal MintClaw Protocol WebSocket server for testing the mintclaw_client channel.
|
mintclaw-echo-server is a minimal MintClaw Protocol WebSocket server for testing the mintclaw_client channel. |
|
integration
|
|
|
fixtures/mcp-streamable-server
command
|
|
|
channels/deltachat
Package deltachat implements a MintClaw channel for Delta Chat, an email-based, end-to-end encrypted messenger.
|
Package deltachat implements a MintClaw channel for Delta Chat, an email-based, end-to-end encrypted messenger. |
|
coding/frontend
Package frontend defines the transport-neutral projection consumed by coding frontends.
|
Package frontend defines the transport-neutral projection consumed by coding frontends. |
|
coding/frontend/agentadapter
Package agentadapter projects stable observations from the shared agent runtime into the coding frontend protocol.
|
Package agentadapter projects stable observations from the shared agent runtime into the coding frontend protocol. |
|
coding/thread
Package thread defines durable local-coding thread identity and metadata.
|
Package thread defines durable local-coding thread identity and metadata. |
|
coding/tui
Package tui contains the bounded Bubble Tea feasibility model admitted by P0.5.
|
Package tui contains the bounded Bubble Tea feasibility model admitted by P0.5. |
|
config
Package config
|
Package config |
|
constants
Package constants provides shared constants across the codebase.
|
Package constants provides shared constants across the codebase. |
|
credential
Package credential resolves API credential values for model_list entries.
|
Package credential resolves API credential values for model_list entries. |
|
diagnosticcapture
Package diagnosticcapture persists finalized diagnostic traces independently of the runtime component that produced them.
|
Package diagnosticcapture persists finalized diagnostic traces independently of the runtime component that produced them. |
|
diagnostictrace
Package diagnostictrace defines MintClaw's bounded diagnostic trace format.
|
Package diagnostictrace defines MintClaw's bounded diagnostic trace format. |
|
events
Package events provides the process-local runtime event bus used to observe MintClaw components without coupling them to agent-specific event envelopes.
|
Package events provides the process-local runtime event bus used to observe MintClaw components without coupling them to agent-specific event envelopes. |
|
fileutil
Package fileutil provides file manipulation utilities.
|
Package fileutil provides file manipulation utilities. |
|
identity
Package identity provides unified user identity utilities for MintClaw.
|
Package identity provides unified user identity utilities for MintClaw. |
|
outbox
Package outbox defines the durable ownership state for outbound delivery.
|
Package outbox defines the durable ownership state for outbound delivery. |
|
patchformat
Package patchformat parses and prepares the bounded Codex patch format used by local and companion workspace tools.
|
Package patchformat parses and prepares the bounded Codex patch format used by local and companion workspace tools. |
|
providers/bedrock
Package bedrock provides a stub implementation when built without the bedrock tag.
|
Package bedrock provides a stub implementation when built without the bedrock tag. |
|
providers/capabilities
Package capabilities defines provider feature metadata without importing a provider implementation or protocol type.
|
Package capabilities defines provider feature metadata without importing a provider implementation or protocol type. |
|
providers/common
Package common provides shared utilities used by multiple LLM provider implementations (openai_compat, azure, etc.).
|
Package common provides shared utilities used by multiple LLM provider implementations (openai_compat, azure, etc.). |
|
providers/httperrors
Package httperrors normalizes provider HTTP failures without adding provider runtime dependencies to the broadly shared common package.
|
Package httperrors normalizes provider HTTP failures without adding provider runtime dependencies to the broadly shared common package. |
|
providers/openai_responses_common
Package openai_responses_common provides shared utilities for providers that use the OpenAI Responses API (e.g., Azure, Codex).
|
Package openai_responses_common provides shared utilities for providers that use the OpenAI Responses API (e.g., Azure, Codex). |
|
tasks
Package tasks provides durable task/run bookkeeping for background work.
|
Package tasks provides durable task/run bookkeeping for background work. |
|
utils
Package utils provides shared, reusable algorithms.
|
Package utils provides shared, reusable algorithms. |
|
testtimings
command
|
|
|
web
|
|
|
backend
command
|
|
|
backend/dashboardauth
Package dashboardauth provides a bcrypt-backed SQLite store for the launcher dashboard password.
|
Package dashboardauth provides a bcrypt-backed SQLite store for the launcher dashboard password. |