zuzuu

Your project directory becomes the coding agent's memory and toolkit — plain files you query on demand, grown by a human-gated loop that learns from how you actually work. And because a module is a table and a note is a row, the same directory grows into your personal application: queryable, conversable, versioned in git.

The host agent you already run — Claude Code, Codex, Gemini CLI, OpenCode, pi — supplies the brain. zuzuu gives it an evolving body of knowledge, memory, actions, and guardrails as plain markdown in your repo. It observes your real sessions, proposes what it learned, and — only with your approval — writes it back. You get the direct lane; the agent gets the gate. We never run a competing agent loop and never drive the host headlessly.

   you converse ──► the agent stages proposals ──► YOU review ──► the app grows
        │                (its only write path)      (the moat)    (a git commit,
        └───────────── your own edits land directly, instantly ──  rollback-able)

npm i -g @zuzuucodes/cli — the command is zz. Zero runtime dependencies, Node ≥ 22.

Everything is an envelope

One file format underlies everything: markdown body + YAML frontmatter, distinguished by type (the only required field). A note is one such file — one fact, optionally runnable. A module is a goal-shaped folder of notes; its module.md is the same envelope. A Project is one repo's whole accumulated knowledge. The hierarchy: note › module › Project — every load-bearing term is defined in the model.

Quickstart

npm install -g @zuzuucodes/cli

cd your-project
zz init                    # plant the Project (.zuzuu/, git-citizen) — or `zz init --root` for a notes-first repo
zz host enable             # wire your agent's lifecycle hooks + the guardrails gate

# … work with your agent normally. zuzuu watches. Then:
zz observe                 # mine your real sessions → evidence-backed proposals
zz review                  # see what it learned, ranked
zz review approve knowledge <id>   # the human gate — the note lands, a generation mints

zz host web                # the workbench: your project as a living map (the World)

Your own rows never wait for a gate:

zz note create crm acme --type account --field company="Acme Corp"   # lands NOW, validated
zz query crm --where "tier>=2" --group-by stage                      # SQL over markdown
zz module import crm --csv leads.csv                                 # one generation, all-or-nothing

What you get

Borrowed, not invented

Where zuzuu sits

• vs agent-harness wrappers (static CLAUDE.md/skills bundles): our modules graduate — the loop grows them from real sessions, through a human gate. A wrapper configures; zuzuu learns.
• vs personal databases & PKM (Notion, Airtable, Obsidian, Tana, Anytype): a module is a table there too — but ours is agent-grown, human-gated (automated memory poisons itself; the gate is the defense none of them ship), git-native, and local-first, zero-dep, plain markdown. No server, no lock-in — your table is a folder you can read.

The safety model, in three lines

• The human gate is the moat. Every agent write passes zz review. One writer (grow/commit.mjs) refuses agent-stamped writes in-process; the generated execution gate denies write verbs at the shell. Structural, not a convention.
• Your writes are validated, not gated — schema-checked, provenance-logged, minted; instant.
• Everything rolls back. A generation is a git commit; rollback is a new forward generation.

Host coverage

Five hosts ship, each built against that host's real on-disk format: Claude Code (transcript JSONL) · Codex (rollout JSONL) · Gemini CLI (logs.json, thin¹) · OpenCode (SQLite) · pi (session JSONL). zz observe mines them all; the lifecycle hook + PreToolUse guardrails gate are wired for Claude Code.

¹ Gemini's logs.json is prompt-only — an honest capture gap, not a core difference.

Documentation

Repo map

Built in the open: every capability proven on real sessions before it counts, recorded in docs/LOG.md; day-by-day on X (@h1902y). Hacking on zuzuu? git clone && npm link.

Personal project, early and changing daily. MIT. Issues/ideas welcome.