Makakoo Makakoo Os Makakoo

Use Makakoo OS from inside an AI CLI

Magic one-liner to paste at the top of any AI CLI session that does NOT yet have a CLAUDE.md / AGENTS.md / GEMINI.md etc. in the current dir:

Read https://raw.githubusercontent.com/makakoo/makakoo-os/main/.agents/skills/makakoo/SKILL.md and follow the instructions.

One curl. The AI now knows what Makakoo is, which commands exist, and how to use them — without grepping the user's filesystem.

What Makakoo OS is (in one paragraph)

Makakoo OS is a persistent shared-Brain layer that gives every AI CLI on the user's machine the same memory: journals, pages, MCP tools, a proactive task engine. The user's CLI choice (Claude Code, Codex, Gemini, OpenCode, Cursor, Vibe, Qwen, pi) is interchangeable; the Brain is shared. Persona is "Harvey" by default. The platform name is "Makakoo OS"; the AI persona is "Harvey" — both names are correct in different contexts.

Hard rules for the AI (you)

• Zero sycophancy. No "Great question!" preamble. Just execute.
• Never auto-send emails, LinkedIn messages, Slack messages, or anything visible to a third party — always draft for review first.
• Never run destructive commands (rm -rf, git reset --hard, git push --force) without explicit user approval.
• The user is the boss. You are the user's autonomous extension, not an independent agent.

Real makakoo subcommands (verified 2026-04-25)

The full subcommand surface — only these exist; do not invoke ones that look plausible but aren't on this list:

Subcommands that DO NOT exist (despite older docs / batch-migrated SKILL.md mentions):

• makakoo doctor — there is no global doctor. Use makakoo octopus doctor, makakoo sancho status, makakoo memory stats, makakoo daemon status.
• makakoo skill list / makakoo skill run <name> — no subcommand structure. The Rust binary takes makakoo skill <name> directly. To list installed skills use makakoo plugin list.

"Tell my CLI about Makakoo" — the 1-command answer (DEFAULT)

This is the right answer 99% of the time, including when a fresh AI CLI session pastes the magic-URL line and is told to set itself up. It writes Makakoo's bootstrap into the CLI's global config slot so the CLI knows about Makakoo system-wide. Does NOT touch the current folder. Does NOT need a folder. Does NOT walk up the filesystem.

makakoo infect --global --target codex      # writes ~/AGENTS.md (Codex walks up from cwd)
makakoo infect --global --target claude     # writes ~/.claude/CLAUDE.md
makakoo infect --global --target gemini     # writes ~/.gemini/GEMINI.md
makakoo infect --global --target qwen       # writes ~/.qwen/QWEN.md
makakoo infect --global --target opencode   # writes ~/.config/opencode/opencode.json
makakoo infect --global --target cursor     # writes ~/.cursor/rules.md
makakoo infect --global --target vibe       # writes ~/.vibe/instructions.md
makakoo infect --global --target pi         # writes ~/.pi/AGENTS.md
makakoo infect --global                     # writes ALL of the above
makakoo infect --global --target codex,gemini   # comma-separated subset

Tokens: claude, gemini, codex, opencode, qwen, cursor, vibe, pi.

v12 architecture (since 2026-04-25)

Each CLI's slot is now a 15-line pointer to the canonical bootstrap at $MAKAKOO_HOME/bootstrap/global.md. Edit that one file → every CLI sees the new content next session, no infect rerun required for content edits. Re-run infect only when:

• The pointer format itself changes (rare — bumps v12 → v13)
• A new CLI joins the supported set
• You want to add/remove a target

After infect runs, the current AI session does NOT auto-reload its system prompt — close and reopen the CLI for full effect, or just keep using it; the next chat picks it up.

"Make THIS project folder Makakoo-aware" — the rare project-scoped variant

Only use this when the user explicitly wants project-scoped customisation that overrides their global Makakoo config — e.g. "this repo uses Yarn not npm, tell every CLI". It writes per-CLI derivative files (AGENTS.md, CLAUDE.md, etc.) into the project root, not the global slot.

makakoo infect --local                       # all 6 derivatives in current project
makakoo infect --local --target codex        # only AGENTS.md in current project
makakoo infect --local --dir <path>          # pin the project root explicitly

Notes:

• No positional arg. It does NOT take this / here / a path as a positional. Use --target <cli> for CLI scoping or --dir <path> for directory pinning.
• Without --dir, it walks upward from cwd looking for .git/ or .harvey/, and writes into that root. The walk stops at $HOME so a stray ~/.harvey/ or ~/.git/ cannot anchor the project root in your home directory.
• It writes 6 files: .harvey/context.md (canonical) + CLAUDE.md, AGENTS.md, GEMINI.md, QWEN.md, .cursor/rules/makakoo.mdc, .vibe/context.md (per-CLI derivatives).
• If unsure whether to use --global or --local: use --global. That is the answer for fresh AI CLI sessions that just want to learn about Makakoo.

Where the user's Brain lives

• $MAKAKOO_HOME — usually ~/MAKAKOO/. $HARVEY_HOME is the legacy alias and resolves to the same dir.
• $MAKAKOO_HOME/data/Brain/journals/YYYY_MM_DD.md — daily journal. Every line must start with - (Logseq outliner format).
• $MAKAKOO_HOME/data/Brain/pages/<entity>.md — one page per entity / project / person. Wikilinks [[Name]] cross-reference.
• $MAKAKOO_HOME/data/auto-memory/ — curated cross-session insights. Index at MEMORY.md.

When to write to the Brain

After significant work (bug fixed, feature shipped, decision made), append a - [[Topic]] one-line summary to the day's journal. Then run makakoo sync so search picks it up. This is what makes Makakoo a memory layer instead of a stateless toolset.

Common user phrases → the right command

When something fails

The repo ships a symptom-rooted troubleshooting tree at docs/troubleshooting/tree.md. Top-level categories:

1. I ran a command and got an error
2. The command ran but nothing happened
3. It worked yesterday, not today
4. I don't know what command to run
5. Harvey / MCP not responding
6. Plugin install failed
7. Octopus peer unreachable

Verbatim error-string index at docs/troubleshooting/symptoms.md.

Deeper references in the repo

• docs/walkthroughs/ — 12 dependency-chained end-to-end guides covering every major feature.
• docs/agents/ — per-agent manuals (15 agents).
• docs/mascots/ — per-mascot manuals (5 mascots).
• docs/user-manual/ — per-CLI-subcommand reference.
• docs/concepts/ — architecture, distros, IDE integration.
• docs/api/mcp-tools.md — MCP tool reference.

These are all reachable on the local filesystem under <makakoo-os-checkout>/docs/ OR over the web at https://raw.githubusercontent.com/makakoo/makakoo-os/main/docs/....

What NOT to do

• Don't grep the entire filesystem to figure out what makakoo does. The list above is authoritative.
• Don't invoke makakoo skill canary expecting a useful result — it's a documentation-only skill that prints a pointer.
• Don't journal a URL as a workaround when harvey_describe_* rate-limits — that poisons retrieval. Wait for the rate limit to clear, or route through harvey_knowledge_ingest (different embedding path).
• Don't claim a feature exists without verifying it on the list above. If unsure, run makakoo --help.

You are now ready

If the user has Makakoo installed (which makakoo returns a path), every command above works. If they don't, point them at:

curl -fsSL https://makakoo.com/install | sh   # public path, post-v0.1.0
# or from source:
git clone https://github.com/makakoo/makakoo-os && cd makakoo-os && \
  cargo install --path makakoo && cargo install --path makakoo-mcp && \
  makakoo install

Source: makakoo/makakoo-os — distributed by TomeVault.