Manage your CLAUDE.md and AGENTS.md across machines and runtimes.

Reuse Markdown sections and choose a profile for each setup.

Claude Code · Codex · Cursor · Pi

Install · Demo · Documentation

Claude and Codex may share your coding conventions, but each also needs instructions of its own. Your work laptop needs a different global setup from a machine running hosted agents. Project files add another layer.

mdmanager lets you reuse the shared Markdown and choose what each runtime gets. Named Global Profiles keep different setups organized, and Context brings global and project instruction sources into one view.

Shared instructions, with room for differences

A Section is an ordinary Markdown file you can reuse in several compositions. Each target has its own ordered list of Sections, so Claude and Codex can share conventions while keeping their runtime-specific instructions separate.

For example:

Edit a shared Section once, then review and apply the affected targets.

If you already have instruction files, your agent can adopt them into mdmanager while preserving their deployed contents.

A Global Profile for each setup

Your work laptop might need company conventions and instructions for interactive development. A hosted agent machine might need instructions for unattended work.

Give each setup a named Global Profile. Each Profile selects the runtime targets it deploys and the Sections included in each target.

mdmanager apply work-laptop --yes

On the hosted machine:

mdmanager apply hosted --yes

Profiles and personal Sections can live in your dotfiles. You handle getting those files onto each machine; mdmanager applies the chosen Profile there. A fresh install does not fetch your Profiles or choose one for the machine. Follow the fresh-machine setup and update workflow to install your shared configuration, select a Profile, and apply later changes.

Read global and project instructions together

Open mdmanager inside a repository and choose Context. You can browse the instruction sources for your selected runtime, with their loading order and contents visible in the same screen.

Context explains why an override takes precedence, which rules load conditionally, and whether a source is excluded or truncated. Switch runtimes to compare their instruction chains.

You can inspect existing files immediately, without configuring mdmanager or adopting them.

mdmanager context --runtime claude
mdmanager context --runtime codex --json

Context describes persistent instruction Markdown on disk for a new session. It does not inspect a running conversation or its system prompt.

Keep personal instructions out of shared project files

Choose the scope that fits the instructions:

Project compositions stay self-contained, so teammates don't need your personal library. Local compositions can reuse your personal Sections across repositories.

Project and Local management require a Git worktree. Runtime behavior still applies: Codex and Pi's AGENTS.override.md replaces AGENTS.md, while Claude's CLAUDE.local.md adds instructions. Cursor has no Global Markdown target.

Work with your coding agent

Point your coding agent to the setup guide:

mdmanager docs start

Then tell it what you want changed. For example:

Read mdmanager docs start and help me organize my Claude and Codex instructions. Reuse the shared coding conventions and keep runtime-specific instructions separate. Prepare the changes for me to review before applying.

Open mdmanager in your terminal to check the result. Browse the sources and review differences while the agent works; the TUI reloads automatically as files change.

When you're happy with the changes, ask the agent to apply them. You can also authorize it to apply from the outset.

Editing a source changes the proposed composition. Apply updates the instruction file your runtime reads. Status shows when changes are waiting to be applied or when someone has edited a managed target directly.

The agent performs instruction edits and Apply through the CLI. You use the TUI to inspect its work.

Install

Install a prebuilt binary for Linux or macOS (x86_64 and ARM64):

curl -fsSL https://mdmanager.ai/install | sh

Installs to ~/.local/bin without sudo. Add it to your PATH if prompted. Run the same command to update. Manual downloads.

Point your coding agent to:

mdmanager docs start

Then run mdmanager inside your repository to inspect instructions in the TUI.

Installer options

The installer verifies the release's SHA-256 checksum. Set MDMANAGER_VERSION=v0.1.0 to select a release or MDMANAGER_INSTALL_DIR=/path/to/bin to choose the destination; pass these variables to sh when piping the installer.

Documentation

The guides also ship inside the binary:

mdmanager docs
mdmanager docs start
mdmanager docs context

See the documentation index for runtime-specific guides. Release notes are in the changelog.

Develop

Building from source requires Rust 1.91.1 or newer:

git clone https://github.com/manuelschipper/mdmanager.git
cd mdmanager
cargo install --locked --path .

cargo test
cargo clippy --all-targets -- -D warnings
cargo fmt --all -- --check

The development toolchain is pinned to Rust 1.91.1. DESIGN.md describes the architecture and ownership rules.

License

MIT