Project rules and imports

Concept

Project rules are Markdown files Matcha CLI injects as instructions at the start of a conversation. The file you should write for Matcha CLI is AGENTS.md at the repo root (and, if needed, in subdirectories).

Matcha CLI also discovers the same family of files other tools use — CLAUDE.md, .claude/rules/, .cursor/rules/, and their home-level twins — when the matching compatibility switch is on (the default).

Import is a different action. /import-claude copies settings (permissions, environment variables, MCP servers, hooks, and extra skill/rule paths) from ~/.claude into Matcha CLI config. It does not replace AGENTS.md. Rules files are read in place; settings are copied when you confirm the modal.

matcha inspect lists every rules file, skill, and MCP server it found, tagged with where it came from.

Why this matters

Repeating “use pnpm,” “never edit generated/,” or “CSS modules in this package” on every turn wastes context and drifts. A short AGENTS.md is the most useful customization you can make.

If you already have Claude or Cursor material, you should not have to retype it. Discovery covers the Markdown. /import-claude covers the JSON settings. matcha inspect is how you confirm both.

What Matcha CLI reads automatically

Named instruction files

In each directory it scans, Matcha CLI looks for these names, in this order, and loads every distinct file it finds:

• Agents.md
• Claude.md
• CLAUDE.md
• CLAUDE.local.md
• AGENT.md
• AGENTS.md

On a case-insensitive disk, Agents.md and AGENTS.md are the same file and count once.

With Claude compatibility on (default), it also reads ~/.claude/ for those names and, at each project level, .claude/CLAUDE.md and .claude/CLAUDE.local.md. Cursor compatibility does the same for ~/.cursor/.

Rules directories

Every *.md file in these folders is loaded (any filename):

Home rules load first (Matcha CLI, then Claude, then Cursor), then project files from the git root down to the current directory. Inside a rules folder, files are alphabetical. Deeper named files appear later and win when instructions conflict.

Outside a git repo, only the current directory is scanned (plus home).

Files ignored by .gitignore are skipped. Put personal overrides in a recognized name such as CLAUDE.local.md and gitignore that name. Custom names like AGENTS.local.md are not discovered at the top level — only inside a rules/ directory.

What to put in `AGENTS.md`

Actionable instructions, not a copy of the README:

# My Project
- Run tests with `pnpm test`
- Never edit files under generated/

Build commands, conventions, and gotchas belong here. Team-wide rules go in the repo. Personal defaults go in ~/.matcha/AGENTS.md or ~/.matcha/rules/.

For one session only, without editing a file:

matcha --rules "Always use TypeScript. Prefer functional components."

Coming from Claude, Cursor, or Codex

Picked up without /import-claude (when the matching compat cell is on):

• Rules — AGENTS.md, CLAUDE.md (including nested), .claude/rules/, .cursor/rules/, and the home-level twins.
• Skills and custom commands — ~/.claude/skills/, ~/.claude/commands/, ~/.cursor/skills/, and the project-level copies. Flat command .md files become slash commands.
• MCP servers — ~/.claude.json, .cursor/mcp.json, project .mcp.json.
• Hooks — .claude/settings.json, including matcher aliases such as Bash.

Each surface is a cell in ~/.matcha/config.toml. Defaults are on. An environment variable beats the file; the file beats the default.

[compat.claude]
skills = true
rules = true
agents = true
mcps = true
hooks = true

[compat.cursor]
skills = true
rules = true
agents = true
mcps = true
hooks = true

rules and agents are independent. Codex skills / rules / agents / mcps / hooks cells are reserved and do nothing today.

Import Claude settings

/import-claude opens a checkbox modal. The same modal opens from the welcome screen with Ctrl+I (or i on the import row).

It scans:

• ~/.claude/settings*.json and project .claude/settings*.json (permissions, env, hooks)
• ~/.claude.json (MCP servers)
• project .mcp.json
• ~/.claude/{skills,rules} and <repo>/.claude/{skills,rules} (as extra search paths)

The list is grouped Global vs Project, then Permissions, Env vars, MCP servers, Hooks, and Paths. Toggle a row, a group, or the whole scope. Confirm writes only the checked items.

Writes are additive:

• Global items → ~/.matcha/config.toml (hooks also go to ~/.matcha/hooks/imported-from-claude.json)
• Project items → <repo>/.matcha/config.toml (and .matcha/hooks/imported-from-claude.json there)

Existing keys and MCP server names are not overwritten. Re-run the command any time; skipped items stay available.

Dismissing the welcome row records that you declined. Matcha CLI then stops silently reading .claude/ settings at runtime for those fallback paths. Discovery of AGENTS.md / CLAUDE.md is unchanged. Run /import-claude later if you change your mind.

Check what was discovered

From the project directory:

matcha inspect
matcha inspect --json

Human output includes:

• Project Instructions — path, scope (project / user / …), approximate token count, and a vendor tag such as [claude] or [cursor] when the file came from that tree. Disabled compat surfaces are still listed and marked.
• Skills, MCP Servers, Hooks — each with an origin label and the same vendor / disabled tags. A skill that lost its bare name shows [collides with /login → /acme:login].
• Harness Compatibility — each cell as on or OFF, with (default), (config), or (env).

inspect walks the disk with every vendor surface on, so you see files that a compat toggle would hide at session start. If the folder is not trusted, repo-local hooks, plugins, and MCP/LSP entries are listed as gated; inspect does not start those servers.