mdmind is a local-first thinking tool for structured maps in plain text.

It gives you two interfaces over the same file:

• mdm: a CLI for viewing maps, rendering Markdown, searching, validating, exporting, and copying examples
• mdmind: a full-screen TUI for navigating, filtering, editing, and reshaping maps

Large idea trees stay calm, searchable, and safe to edit with a keyboard.

License: Apache-2.0

Why mdmind

mdmind is good for:

• product and feature planning
• research and writing maps
• prompt libraries
• project breakdowns
• backlog shaping
• keyboard-first personal planning

It is not trying to be:

• a rich document editor
• a team wiki
• a freeform diagram canvas

What A Map Looks Like

Maps are plain-text tree files with lightweight inline structure:

• #tag for grouping and workflow markers
• @key:value for structured metadata
• [id:path/to/node] for stable deep links
• [[target/id]] or [[rel:kind->target/id]] for cross-branch references
• | detail text for longer notes attached to a node

Example:

- Onboarding Research #project @status:active [id:onboarding]
  | Turn scattered notes, interviews, and generated research into a decision map.
  - Core Question #question [id:onboarding/question]
    - Where do new users lose momentum first?
  - Evidence #source [id:onboarding/evidence] [[rel:informs->onboarding/decision]]
    - Interview notes mention setup vocabulary friction
    - Support tickets cluster around first-map examples
  - Decision #decision @owner:jason [id:onboarding/decision]
    - Ship a guided starter map before adding more settings
  - Follow-ups #todo @status:active [id:onboarding/follow-ups] [[onboarding/evidence]]
    - Review five more sessions
    - Draft release note

These files stay readable in normal Markdown tools. mdmind adds structure and navigation on top of that plain-text shape.

Install

For public installs, GitHub Releases are the source of truth.

• macOS:

brew tap dudash/tap
brew install mdmind

• Linux: install from the release tarball
• Windows: install from the release zip

For local development from this repo:

cargo install --path .

That installs both:

• mdm
• mdmind

More install and release detail lives in docs/manual/INSTALL_AND_RELEASE.md. Release notes live in CHANGELOG.md and can be read locally with mdm changelog; use mdm changelog --plain when you need raw Markdown. To check GitHub Releases for a newer build when you have network access, run mdm version --check.

For Codex, Claude, or other agent clients, see plugins/mdmind/README.md.

Quick Start

Create a map from a starter template:

mdm init roadmap.md --template product

For local task decomposition and agent handoff:

mdm init TODO.md --template todo

Inside mdmind, press t / T to add a TODO child or sibling and Space to toggle a focused [ ] / [x] task. Search with task:open, task:blocked, or task:done when you want checkbox-aware filters.

Open the TUI:

mdmind roadmap.md

Open an ordinary Markdown file as a read-only document:

mdmind README.md
mdmind --as markdown README.md

Inside that Markdown view, press i to import a native map beside the source as README-mind.md; the original Markdown stays unchanged, the imported map opens immediately, and the map includes a #lossy-summary section that names the source, calls out formatting loss, and reports whether non-empty text lines were dropped.

Inspect a map from the CLI:

mdm view roadmap.md
mdm find roadmap.md "#todo"
mdm links roadmap.md

View an ordinary Markdown file from the CLI:

mdm view-markdown README.md

Copy bundled example maps onto your machine:

mdm examples list
mdm examples copy all

Core Ideas

• one plain-text map format, two interfaces
• local-first files with small sidecars for session state, views, checkpoints, navigation memory, and UI settings
• focused views for working inside large maps without losing structure
• built-in search, browse, saved views, ids, relations, and detail notes
• safe editing with undo, redo, checkpoints, and autosave/manual save modes

Read Next

If you are new:

• docs/README.md
• docs/help/USER_GUIDE.md
• docs/manual/TUI_WORKFLOWS.md
• docs/manual/USING_MDMIND_AS_OUTLINER.md
• docs/agents/AGENT_USAGE.md

If you want specific features:

• spec/README.md
• docs/reference/QUERY_LANGUAGE.md
• docs/reference/IDS_AND_DEEP_LINKS.md
• docs/reference/CROSS_LINKS_AND_BACKLINKS.md
• docs/reference/NODE_DETAILS.md
• docs/agents/SKILLS_CUSTOMIZING.md
• docs/manual/SAFETY_AND_HISTORY.md
• docs/manual/TEMPLATES.md
• examples/README.md

If you want product docs:

• docs/product/README.md
• docs/product/shipped/README.md
• docs/product/prds/

If you are working on the repo:

• DEVELOPER.md