claude.md is a plain markdown file Claude Code reads when it starts a session. It gives Claude stable context about your project: conventions, commands, architecture, and preferences. Anthropic ships the convention; the file is just markdown.

Where do I put claude.md?

The most common place is your project root — Claude Code picks it up automatically. You can also keep a global claude.md in ~/.claude/ for cross-project preferences.

What goes in a claude.md file?

Anything you'd otherwise repeat every session: build/test commands, code style rules, domain vocabulary, gotchas, links to key files, and how you want Claude to answer.

Back to home

Guide

claude.md, explained

The project context file — and how to make it portable

claude.md is a plain markdown file Claude Code reads when it starts a session. It's how you give Claude stable context about a project — conventions, commands, architecture, tone — without pasting it into every chat.

Where it lives

Project root. Put claude.md at the top of your repo. Claude Code picks it up when you run it in that directory.
Global. A file at ~/.claude/claude.md applies across every project — good for preferences ("answer in short paragraphs", "prefer TypeScript over JavaScript").

What to put in it

Commands. How to build, test, lint, and deploy.
Style. Naming, formatting, forbidden patterns.
Architecture. Where the modules live and how they talk.
Vocabulary. Domain terms you use that Claude won't guess.
Gotchas. The three things that always break.

Example:

# Project: acme-api

## Commands
- Build: `pnpm build`
- Test one file: `pnpm vitest run <path>`
- Lint: `pnpm lint`

## Style
- No default exports.
- Prefer named types over interfaces.
- Never touch `src/generated/**`.

## Gotchas
- Migrations must be idempotent.
- `ctx.user` is null in cron handlers.

The limit of a single file

claude.md is per-project and per-machine. You end up with copies in every repo, drift between them, and none of it reaches ChatGPT, Codex, or Claude Desktop chats outside the terminal.

A networked claude.md

Muninn works like claude.md that lives in one place and every assistant can read. Point Claude Code at Muninn via MCP and it can pull the right note (by title, by tag, by search) instead of re-reading a whole static file. Update the note once, and every assistant sees the change on its next call.

One source instead of a file per project.
Retrieved on demand — no per-turn token bloat.
Same notes in Claude Desktop, Claude Code, ChatGPT, Codex.