Many bodies. One mind. Open-source autonomous cognitive extension that gives every AI CLI on your machine the same persistent brain.
AI agents don't remember. And they definitely don't share memory with each other. Every Claude session starts from zero. Every Gemini conversation is a goldfish. Every CLI has its own fishbowl.
Makakoo OS fixes this. One install gives the agentic hosts on your machine the same home: Claude Code, Gemini CLI, Codex, OpenCode, Vibe, Cursor, Qwen, Kimi, pi, and IDE assistants like VSCode Copilot, Continue, Cline, and JetBrains AI. Chat systems such as Telegram, Discord, Slack, email, voice, and web are not infected hosts. They connect through agent slots and transports. Same Brain, same rules, same tools, different doorway.
Your notes, your decisions, your arguments with yourself from three months ago are retrievable by the next assistant you open. No context-reset ceremony.
| Capability | Status |
|---|---|
| Infect AI CLIs with a shared bootstrap block (open-ended roster — 9 today: Claude / Gemini / Codex / OpenCode / Vibe / Cursor / Qwen / Kimi / pi) | ✅ macOS + Linux + Windows |
| 4 IDE-assistant hosts (Copilot / Continue / Cline / JetBrains) | ✅ detection + writers |
| Persistent Brain (canonical Logseq journals/pages + optional Obsidian, Logseq, plain-Markdown, and OKF enrichment) | ✅ |
| Portable knowledge interchange | ✅ local-only OKF v0.1 validation, import, and export via makakoo brain |
| Superbrain search — FTS5 + vector + LLM synthesis | ✅ |
| Headroom context compression for bulky tool output | ✅ included in the default core distro via tool-headroom |
Capability-sandboxed plugin system (plugin.toml manifests) |
✅ core catalog with skills, agents, MCP tools, SANCHO tasks, and patterns |
| Lope validator ensemble | ✅ optional in-house companion project, offered by makakoo setup lope |
| SANCHO proactive task engine | ✅ native + plugin tasks, including optional auto-update checks |
| Makakoo OS updates | ✅ makakoo update, plus auto/manual mode in makakoo setup updates |
Supervised agent runtime — makakoo agent create --specs <PATH> compiles a scoped AgentSpec into a pinned DeepSeek Harness project; start, prompt, health, restart, and destroy own the lifecycle |
✅ local authenticated runtime; channel adapters are the next slice |
| Unix domain socket + Windows named-pipe IPC for plugins | ✅ |
| 6 distros published (minimal, core, federation, sebastian, creator, trader) | ✅ |
| Shell completion (bash, zsh, fish, elvish, powershell) | ✅ |
| Signed release artifacts (Apple notarization + Authenticode) | 🟡 runbook ready, certs pending |
| Homebrew tap / winget submission | 🟡 manifests drafted, submission post-launch |
| Fresh-VM smokes on all three OSes | 🟡 scripted, human-supervised runs pending |
Already running an AI CLI (Claude Code, Codex, Gemini CLI, OpenCode,
Cursor, Vibe, Qwen, Kimi, pi)? Paste this single line into the chat — the AI
fetches one URL, learns every real makakoo command, the Brain layout,
the troubleshooting tree, and what not to do, all from one canonical
SKILL.md. No filesystem grepping, no guessing:
Read https://raw.githubusercontent.com/makakoo/makakoo-os/main/.agents/skills/makakoo/SKILL.md and follow the instructions.
That's the orientation layer. Below is the actual install.
First-time user? Open docs/getting-started.md — a step-by-step guide with per-OS instructions, expected output at every step, and common-error fixes inline.
Already comfortable in a terminal? The short version:
macOS / Linux — one-liner. Drops pre-built binaries under ~/.local/bin/ and auto-execs makakoo install, which itself hands off to the interactive setup wizard. End state: every detected AI CLI infected, daemon running, you're inside the wizard.
curl -fsSL https://makakoo.com/install.sh | bashmacOS / Linux — Homebrew alternative:
brew install traylinx/tap/makakoo
makakoo install # runs distro + daemon + infect, then hands off to the wizardWindows — PowerShell one-liner (Developer Mode must be on):
iwr -UseBasicParsing https://makakoo.com/install.ps1 | iexFrom source — every platform, useful for contributors:
git clone https://github.com/makakoo/makakoo-os
cd makakoo-os
cargo install --path makakoo
cargo install --path makakoo-mcp
makakoo install # distro + daemon + infect + health, then hands off to the wizardmakakoo install always finishes with the interactive wizard in a TTY shell. Skip with --no-setup (or MAKAKOO_NO_AUTORUN=1 on the curl-pipe) for unattended installs. Re-enter any wizard section later with makakoo setup --only <section>. See docs/user-manual/setup-wizard.md.
First time using Makakoo? After install, start at Walkthrough 01 — Fresh install on a new Mac. The walkthroughs are a 14-guide tour through every major feature — copy-paste runnable, dependency-chained, in plain language.
Update — one command, auto-detects how you installed:
makakoo update # cargo / brew / curl-pipe — picks the right path
makakoo update --dry-run # preview without spawning
makakoo update --reinfect # also rewrite + verify CLI bootstrap fragments
makakoo upgrade # legacy aliasFresh setup defaults to automatic 24h Makakoo OS updates via SANCHO. Existing
installs stay idle until makakoo setup updates writes
$MAKAKOO_HOME/config/updates.toml; switch auto/manual there any time.
See docs/upgrade.md for the walkthrough and docs/user-manual/makakoo-update.md for flags.
Uninstall — symmetric inverse:
makakoo uninfect # strip bootstrap from every CLI slot
makakoo daemon uninstall # remove the auto-launch agent
rm -rf ~/.makakoo ~/MAKAKOO| I want to... | Read |
|---|---|
| Install Makakoo from zero (step-by-step, beginner-friendly) | docs/getting-started.md |
| See what I can do with Makakoo day-to-day | docs/use-cases.md |
| Import, validate, or export portable knowledge bundles | docs/user-manual/makakoo-brain.md |
| Understand the setup wizard's sections | docs/user-manual/setup-wizard.md |
| Update Makakoo safely, manually or automatically | docs/upgrade.md, docs/user-manual/makakoo-update.md |
Look up a specific makakoo subcommand |
docs/user-manual/ |
| Run durable child-agent work without transcript floods | docs/user-manual/makakoo-agent-session.md |
| Use Lope for multi-model review, votes, compare, and sprints | docs/user-manual/setup-wizard.md#sections |
| Create and run a supervised agent | docs/walkthroughs/dsh-agent-runtime.md, docs/user-manual/agent.md |
| Run the legacy Flue channel compatibility path | docs/walkthroughs/flue-telegram-bot.md |
| Fix something that broke | docs/troubleshooting/ |
| Understand architecture / internals | docs/concepts/ and spec/ |
| Write or publish an adapter | docs/adapters.md, docs/adapter-publishing.md |
| Answer a yes/no question ("does it phone home?", "is it free?") | docs/faq.md |
# Ask your Brain a question — FTS retrieval fused with LLM synthesis
makakoo query "what did I decide about the database migration?"
# Search the Brain full-text
makakoo search "polymarket"
# Export a local OKF v0.1 knowledge bundle
makakoo brain export --source default --out ~/exports/makakoo-okf
# Install a plugin from the shipped core set
makakoo plugin install skill-research-arxiv --core
# See what's registered (native Rust tasks + manifest-driven plugins)
makakoo sancho status
# Open a durable child-agent session and read only the evidence slice
makakoo agent-session open --name repo-audit --role explore --task "Inspect this repo" --workspace .
makakoo agent-session eval repo-audit --wait
makakoo agent-session read repo-audit --section EVIDENCE
# Preview what infect would do, then commit
makakoo infect --global --dry-run
makakoo infect --global
# Grant an agent temporary write access to a directory outside the baseline
makakoo perms grant ~/code/scratch/ --for 1h
makakoo perms list
makakoo perms audit --since 1h # every grant / revoke / denialSee docs/user-manual/makakoo-perms.md
for the full perms subcommand reference, the rejected-write
conversational flow, and the v0.3.1 + v0.3.2 + v0.3.3 hardening
details (rate-limit decrement on revoke, denial audits with
reason:* taxonomy, origin_turn_id enforcement on conversational
channels, grant ownership check on revoke, SANCHO purge idempotency,
and the structured list --json envelope).
| Path | Role |
|---|---|
makakoo-core/ |
Engine library — platform, config, LLM client, superbrain (FTS5 + vectors + graph), SANCHO, capability socket + grant resolver + audit log |
makakoo-mcp/ |
MCP stdio server — NDJSON JSON-RPC, 40+ tools, drop-in for any MCP client |
makakoo/ |
CLI binary — search, query, sancho, plugin, distro, daemon, infect, uninfect, skill, secret, mcp, completion, agent-session, handle |
makakoo-platform/ |
Per-OS adapter — launchd (macOS), systemd (Linux), auto-launch (Windows), POSIX symlinks + Windows Dev Mode symlinks |
makakoo-client/ + makakoo-client-py/ |
Plugin client libraries (Rust + Python) over the capability socket |
plugins-core/ |
Shipped plugin catalog — skills, agents, MCP tools, SANCHO tasks, patterns, and bootstrap fragments |
distros/ |
6 distro bundles — minimal, core, federation, sebastian, creator, trader |
install/ |
install.sh / install.ps1 + shell completion guide |
distribution/ |
Packaging metadata — Homebrew formula, winget manifest, cargo-dist config |
spec/ |
Frozen v0.1 architecture + ABI contracts |
docs/ |
Release signing runbook, relocate runbook, roadmap |
MAKAKOO_HOME— root for Brain, config, logs, plugins, state. Defaults to~/MAKAKOOtoday; moves to~/.makakoo/per the relocate runbook post-launch.HARVEY_HOMEis a legacy alias that resolves to the same dir.AIL_BASE_URL— LLM gateway base URL. Defaulthttp://localhost:18080/v1(switchAILocal).AIL_API_KEY— API key for the LLM gateway. Store viamakakoo secret set AIL_API_KEY— writes to the OS keyring (Keychain / Secret Service / Credential Manager).MAKAKOO_SOCKET_PATH— plugin-side canonical env var for the capability socket. Set automatically bymakakoo skill <name>when spawning a plugin.
cargo build --release --workspace
cargo test --workspace
cargo clippy -p makakoo-platform --all-targets -- -D warningsRelease profile: lto=true, strip=true, opt-level="z", codegen-units=1, panic="abort". Stripped binaries are roughly makakoo ~5 MB and makakoo-mcp ~4.7 MB on aarch64-apple-darwin; sizes drift slightly between releases.
This is a community-built open-source project. Contributions welcome across code, docs, mascots, design, translation, testing, ideas, and sponsorship — every category is a first-class citizen. See CONTRIBUTING.md for the workflow.
- MIT licensed. Forever.
- Local-first. Your data lives on your machine. No telemetry.
- No VC. No acquisition path.
- Every mascot has a named maintainer. Every contributor is recognised.
- CHANGELOG — user-visible changes per release
- docs/RELEASE_SIGNING.md — Apple notarization + Windows Authenticode runbook
- docs/PHASE_H4_RELOCATE.md —
~/MAKAKOO → ~/.makakoo/runtime-relocation runbook - install/completions/README.md — shell completion install + dynamic plugin-name wrappers
- spec/CAPABILITIES.md §1.11 — three-layer write-permission model (v0.3)
- spec/USER_GRANTS.md v1.3 — user-grants file format, lock protocol, CLI + MCP reference
- spec/USER_GRANTS_THREAT_MODEL.md — adversary register, residual risks (R2 fully closed in v0.3.2, ownership gate added in v0.3.3)
- docs/user-manual/makakoo-perms.md —
makakoo permscommand reference - spec/ — frozen v0.1 architecture + ABI contracts
MIT — see LICENSE.
🦉 Makakoo OS · an open project · MIT · no VC · no telemetry · eat sleep go bananas repeat 🍌