---
slug: agents-md
kind: runbook
status: docs-checked
sh: https://insidethemachine.ai/install/agents-md.sh
ps1: null
json: https://insidethemachine.ai/install/agents-md.json
page: https://insidethemachine.ai/setups/agents-md
---

# Install: AGENTS.md

A simple open format, basically a README for coding agents, that tells them how to work in your repo.

**Run status: Not run: commands checked against the official docs only.** Commands checked against the official docs on 2026-10-15. Not run end to end.

**This script:** The wrapper scripts are generated from the site data. Every .sh passed bash -n and shellcheck and ran in plan mode on Linux (Debian 13). Every .ps1 passed the PowerShell parser and chat.ps1 ran in plan, verify and rollback mode under PowerShell 7 on Linux with Windows calls mocked. Not run on macOS or real Windows.

**Run through this script:** 2026-10-16, Debian 13 box: install wrote AGENTS.md and the check passed; a second run left the existing file alone; rollback ran `git rm` (refuses a staged file, by design).

## One command

```bash
curl -fsSL https://insidethemachine.ai/install/agents-md.sh | bash
```

Actions: `| bash -s -- plan` (print only), `verify`, `rollback --yes`. Env: ITM_RAM. Read the script first: `curl -fsSL https://insidethemachine.ai/install/agents-md.sh | less`.

Lines marked YOU RUN are not run by the script (servers, interactive apps, your own files). The script prints them at the end, in order.

## Steps

### macOS

Install:

1. **Install AGENTS.md**
   - run: `cat > AGENTS.md <<'EOF' …`
2. **Configure (your choices)**
   - note: point your agent at the repo; agents that support AGENTS.md read it automatically

Verify:

- `test -f AGENTS.md && head -5 AGENTS.md` → expect: file exists at the repo root

Rollback:

- run: `git rm AGENTS.md   # or: rm AGENTS.md`

### Linux

Install:

1. **Linux: same steps as macOS**
   - note: Our data lists Linux as supported but has no separate Linux steps, so these are the macOS steps. brew lines are skipped; install those tools with your package manager.
2. **Install AGENTS.md**
   - run: `cat > AGENTS.md <<'EOF' …`
3. **Configure (your choices)**
   - note: point your agent at the repo; agents that support AGENTS.md read it automatically

Verify:

- `test -f AGENTS.md && head -5 AGENTS.md` → expect: file exists at the repo root

Rollback:

- run: `git rm AGENTS.md   # or: rm AGENTS.md`