Mudroom

A modular notepad for you and your AI agents

Mudroom is an open-source notepad designed to be used by AI agents and by you. Notes are plain markdown in ~/.mudroom/. Agents write to them with the mudroom CLI; you read and edit the same files. It's the shared entryway for your work.

Why

Mudroom is designed to be a shared, human-readable, cross-agent scratchpad. One folder of markdown, a tiny CLI any agent can call, and a live web view that you can customize.

Guiding principles

• Transparent. Mudroom is open source. The code is there to be inspected, and new features can be requested — nothing about how your agents share state is a black box. (Open an issue to ask for a feature.)
• Modular. Mudroom is built to be customized. Your AI agents can shape it to fit their workflow — for example, re-theme the web UI on the fly with mudroom theme set mode dark or mudroom theme set colors.accent '#5eead4', scope notes into per-project folders, or point the storage root anywhere with --dir / MUDROOM_DIR.
• Documentation first. Mudroom is a shared space for you and your agents, so documentation is how your agents learn to use it. mudroom init writes a usage block into your agent config files and installs agent skills, so the tool explains itself the moment it's installed.

Install

npm i -g mudroom      # or: npx mudroom <command>
mudroom init          # creates ~/.mudroom and tells your agents about it

mudroom init seeds a scratchpad, writes a short usage block into ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md, and installs the agent skills (notepad + theming) for Claude Code and Codex so your agents discover the tool. Use --no-skill to skip the skills, and --no-claude-md / --no-agents-md to opt out of either config file.

Usage

# Append to the shared scratchpad (the default note)
mudroom append "decided to use diff3 for merges"

# Scoped notes — folders organize things
mudroom append projects/acme "deploy blocked on missing NPM_TOKEN"
mudroom append projects/acme "ran migration 0007" --timestamp
mudroom append projects/acme "check retries" --section "TODO"

# Read, list, search
mudroom show projects/acme       # add --raw for body only
mudroom list
mudroom list projects/
mudroom outline projects/acme    # heading structure (anchors + levels)
mudroom search "NPM_TOKEN"

# Human conveniences
mudroom add projects/acme --title "Acme"   # create a new empty note
mudroom edit projects/acme     # opens $EDITOR, saves with merge-safe conflict handling
mudroom open projects/acme     # opens the note in the running web UI
mudroom rm projects/acme
mudroom gc                     # delete uploaded assets no note references anymore

Pass --json to any command for machine-readable output (agents should always use it). Override the storage root with --dir <path> (or MUDROOM_DIR). The web UI and theme commands are covered below.

Commands

| Command | What it does | |---|---| | mudroom init | Create the mudroom root, seed a scratchpad, tell your agents about it | | mudroom append [ref] [text...] | Append text to a note (creates it if missing) | | mudroom add <ref> [text...] | Create a new note | | mudroom list [scope] | List notes, optionally within a scope | | mudroom show <ref> | Print a note (--raw for body only) | | mudroom outline <ref> | Print a note's heading structure | | mudroom search <query> [scope] | Full-text search across notes | | mudroom edit <ref> | Open a note in $EDITOR (merge-safe save) | | mudroom open <ref> | Open a note in the running local web UI | | mudroom rm <ref> | Delete a note | | mudroom gc | Delete uploaded assets no note references anymore | | mudroom serve | Start the local web UI | | mudroom theme ... | Inspect and edit the UI theme (see THEMING.md) |

Note refs

A note ref is a slash path: scratchpad, projects/acme, projects/acme/deploy. It maps directly to a file: ~/.mudroom/projects/acme.md. No ref given to append defaults to scratchpad.

How it works

• Storage: one markdown file per note, with YAML frontmatter, under ~/.mudroom/. Override the location with --dir or MUDROOM_DIR.
• Safe concurrent writes: append takes a per-file lock and writes atomically, so parallel agents never lose each other's writes. A write aborts rather than commit if its lock is reclaimed mid-flight, and the CLI retries briefly on contention — so a fleet of agents hammering one note stays lossless.
• Merge, don't clobber: edit captures the note as you opened it and does a 3-way merge on save. A human edit and an agent append usually merge cleanly; a true overlap is preserved in a <note>.conflict.md instead of being overwritten.
• Keep notes small: every write rewrites the whole file under its lock, so a single note that grows into the multi-megabyte range makes each append slower (and, past the lock's stale window, risky). Scope writes to per-task notes like projects/<x> rather than letting one shared note grow unbounded.

Exit codes

0 ok · 1 error · 2 not found · 3 already exists · 4 bad path · 5 busy (retry).

Multi Agent support

Tested with 50 agents parallel write with no data loss. Try it with npm demo

Web UI

mudroom serve starts a local web app (default http://localhost:4321) to view and edit notes with live updates — when an agent appends via the CLI, the page updates in real time. Editing is merge-safe (3-way merge; conflicts are preserved, never clobbered). The UI is styled with the "Warm Mudroom" design system (see DESIGN.md).

With the server running, mudroom open <ref> opens a note directly in the web UI.

Web UI Theming

You can customize the web UI theme with /mudroom-theming

| UI | Prompt | | --- | --- | | | Default | | | /mudroom-theming make mudroom look like an 8 bit retro website | | | /mudroom-theming make it dracula themed |

Roadmap

• More customizable sections
• Ability to add custom views (Dashboards, Charts, Graphs, Etc)
• Drop your feature requests in issues

Contributing

Issues and PRs are welcome. See CONTRIBUTING.md for setup and the test/lint/typecheck gate, and our Code of Conduct. For security reports, see SECURITY.md.

License

Released under the MIT License.