Mulch CLI
The ml CLI keeps agent expertise as JSONL in the repo: conventions, failures and decisions every team agent reads after a clone
- 339 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The Claude Code hook and files in `.mulch/` change the repository, and records end up in git history
- The agent writes what it considers a lesson, so mistaken records spread to the whole team
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/mulchDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The Claude Code hook and files in `.mulch/` change the repository, and records end up in git history
- The agent writes what it considers a lesson, so mistaken records spread to the whole team
This is third-party code. Review the repository files before installing.
What it does
Mulch installs the `ml` utility, which maintains a `.mulch/` folder in the repository. Before finishing a task the agent calls `ml record` to write down what it learned, and at session start `ml prime` hands it an index of what has accumulated. There is no model inside Mulch: the utility stores and serves records. Records live in `.mulch/expertise/<domain>.jsonl`, one file per knowledge domain and one record per line. There are six types: convention, pattern, failure, decision, reference and guide. A record's class (foundational, tactical or observational) sets its shelf life, and optional anchors tie it to files, commits and tasks. The folder goes into git, so a clone of the repository brings the team's expertise along. `ml prime` prints a compact index within a token budget (4000 by default) and ranks failures and confirmed records higher. `ml search` ranks by BM25, `ml stale` finds outdated records, `ml prune` moves the excess to an archive. `ml setup claude` installs a hook for Claude Code, cursor and codex are supported too, and `ml onboard` prepares a snippet for AGENTS.md or CLAUDE.md.
Who it is for. Teams where several agents work on one repository and repeat the same mistakes from session to session.
Good fit when
- An agent runs VACUUM inside a transaction for the second time, and the lesson should be saved as a failure with a fix
- A newcomer clones the repository and their agent already knows the database and API conventions
- Before a task you want only records about the files being changed: `ml prime --files src/foo.ts`
- Accumulated knowledge goes stale, and `ml stale` shows records whose files changed often
Not a fit when
- You need vector memory with embeddings: Mulch searches JSONL files with BM25
- Knowledge has to travel between machines without git
- A single CLAUDE.md with a few rules is enough
- The environment has neither Bun nor Node: the main install path uses Bun, the fallback uses `npx`
Example request
Record a failure in Mulch: VACUUM inside a transaction corrupts the SQLite database, the fix is to run VACUUM outside transactionsLimitations
- The agent decides when to call `ml record`. The recording rule belongs in AGENTS.md or CLAUDE.md, and `ml onboard` prepares a snippet.
- Records sit in git as plain text, so keep secrets and personal data out of them.
- Staleness is judged by the number of commits in anchored files and by record shelf life, the utility does not verify the meaning.
- The main install path uses Bun, the fallback uses `npx @os-eco/mulch-cli`.
How to disable. Remove the hook that `ml setup claude` added from the agent settings. If the expertise is no longer needed, delete the `.mulch/` folder. Uninstall the package with the same manager that installed it.
FAQ
Where does Mulch keep expertise?
In `.mulch/expertise/` at the repository root: one JSONL file per domain, one record per line. Git tracks the folder, and `ml sync` validates, stages and commits the changes.
How do I connect Mulch to Claude Code?
Run `ml init`, then `ml setup claude`: the command installs a hook served by `ml hook`. `ml onboard` prints a rules snippet for CLAUDE.md.
How many tokens does ml prime output take?
The index is capped at 4000 tokens by default. The `--budget` flag changes the cap, and `--files` keeps records for the files you need.
Does Mulch work with Cursor and Codex?
`ml setup` installs hooks for claude, cursor and codex. `ml setup --list` prints every option.
How do I find outdated records?
`ml stale` lists records whose anchored files changed in at least five commits, went missing or outlived their shelf life without confirmations. `ml prune` moves such records to the archive.
Discussion
No questions or reviews yet.
Related
CLI toolsTasks, docs, specs and decisions live as markdown files in your repository, and the agent reads them through the CLI and MCP
A 2.4 KB charter for CLAUDE.md and three on-demand skills: the agent stops guessing, verifies results and gates irreversible steps
A CLI that analyses a repository in six model phases and writes AGENTS.md or CLAUDE.md, with ExecPlan planning on top.
Over twenty skills for coding agents: MCP and hooks, plan mode, a bug-fix protocol, prompting and a bash safety hook
A library of 30-plus instruction skills for coding agents: planning, building, testing, hallucination guards and shipping
Code graph and project memory in one Rust program: the agent gets excerpts with file and line citations
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Mulch (this card) | no | 339 | ||
| Beads | no | 28,694 | a task tracker with a dependency graph on Dolt, while Mulch stores accumulated knowledge | |
| agent-memory | no | 4,315 | Markdown as the source of truth with a SQLite index, while Mulch keeps typed JSONL records | |
| ByteRover CLI | yes | API key | 4,946 | the brv memory layer with git-like versions and an MCP server |
README in short
The README begins with the idea that an agent starts from zero every session and notes that Mulch is passive. Next come installation, a quick start, a table of about thirty commands, output formats, the layout of the `.mulch/` folder and the record types.