AGENTS.md Compiler

Most teams using AI coding agents end up maintaining the same project rules in 3–4 places: .cursorrules for Cursor, CLAUDE.md for Claude Code, .github/copilot-instructions.md for Copilot, often AGENTS.md too. They drift. People update one and forget the others.

terso emit makes AGENTS.md canonical and treats the rest as compilation output.

AGENTS.md  →  CLAUDE.md
            →  .cursorrules
            →  .github/copilot-instructions.md

How it works

You write project rules once in AGENTS.md.
terso emit writes them out to whichever per-agent files your repo uses.
Each emitted file starts with a marker comment so re-running emit is safe and won't clobber files you maintain by hand.

Why AGENTS.md?

It has the broadest cross-tool acceptance and is already used as a canonical format by Codex and others. Picking an existing standard means no new file format to learn.

Auto-detection

emit only writes to targets whose presence hints exist in your repo:

Agent	Detected via
Claude Code	`CLAUDE.md` or `.claude/`
Cursor	`.cursorrules` or `.cursor/`
GitHub Copilot	`.github/copilot-instructions.md`

On a fresh repo with no hints, emit writes all three so you can pick what to keep.

Safety

emit won't overwrite files you maintain by hand. The first write tags each output file with this marker:

<!-- Generated by terso from AGENTS.md. Do not edit; run `terso emit` to update. -->

Re-runs only overwrite files that have this marker. To overwrite an unmarked file, use --force.

CI gate

Add a check to your pipeline so AGENTS.md and the emitted files can never drift:

# .github/workflows/agents.yml
name: agents-config-sync
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx terso-cli emit --check

This fails the build if anyone hand-edits CLAUDE.md or .cursorrules without updating the canonical AGENTS.md.

Watch mode

While iterating on rules, run:

terso emit --watch

Every save of AGENTS.md re-emits the per-agent files immediately. Pair this with your editor's autosave for a tight feedback loop.

Cherry-picking targets

If you only use Claude Code and Cursor:

terso emit --targets claude,cursor

Or remove the unwanted file once and emit will skip it on subsequent runs (no presence hint = not emitted).