AGENTS.md Support

SideButton uses AGENTS.md — the open, engine-agnostic format for agent instructions — as the canonical instruction file for every workspace it deploys.

Whatever you write in Portal → Files → Instructions lands on the agent's VM as AGENTS.md in the workspace root. Any coding agent that reads the format picks it up with no SideButton-specific configuration: Codex, Amp, Jules, Cursor, and the rest.

What lands on the agent

Applying a config set writes these files into each workspace directory, plus a small .sb-instructions-sha bookkeeping sidecar (see Bringing your own AGENTS.md):

File	Contents	Who reads it
AGENTS.md	Your instructions, verbatim	Every AGENTS.md-aware agent
CLAUDE.md	A two-line @AGENTS.md import	Claude Code
.mcp.json	The workspace's MCP servers	Any MCP client

~/workspace/
├── AGENTS.md              # canonical — your instructions
├── CLAUDE.md              # generated pointer: @AGENTS.md
├── .mcp.json
├── .sb-instructions-sha   # bookkeeping — marks AGENTS.md as SideButton-managed
└── <project-repos>/

Why CLAUDE.md is still there

Claude Code reads CLAUDE.md, not AGENTS.md. Rather than shipping the same text twice — which makes an agent that reads both files load your instructions twice and burn context — SideButton writes a two-line CLAUDE.md that imports the canonical file:

<!-- Generated by SideButton. Canonical instructions: AGENTS.md — edit that file. -->
@AGENTS.md

One source of truth, both engines covered.

Editing instructions

Edit AGENTS.md, not CLAUDE.md. The pointer is regenerated on every config apply, so edits to CLAUDE.md are overwritten. Two ways to change what an agent reads:

• Portal → Files → Instructions, then Save & apply — the durable path. The text is stored on the workspace (or on a named config set) and re-applied to every agent assigned to it.
• Edit AGENTS.md on the VM — useful mid-session, but the next config apply replaces it.

Bringing your own AGENTS.md

If a workspace already contains a hand-authored AGENTS.md — one you committed or wrote on the VM before SideButton ever applied a config there — SideButton will not overwrite it. Your file wins; the portal's instructions are written to CLAUDE.md instead, exactly as they were before AGENTS.md support existed, so the workspace still gets them. That stays true on every later apply.

SideButton tells its own file from yours with a .sb-instructions-sha sidecar it writes next to any AGENTS.md it created. It writes AGENTS.md only when one of these holds:

• the file is absent, or empty — a stray touch protects nothing;
• the sidecar is beside it, proving an earlier apply created it;
• the file already holds exactly the text being applied, so adopting it changes no bytes.

Anything else — a non-empty file, different text, no sidecar — is yours and is left alone. Deleting the sidecar hands the file back to you, and editing CLAUDE.md never changes who owns AGENTS.md.

Deleting the sidecar freezes the file

Once the sidecar is gone, later applies treat AGENTS.md as yours and divert the text to CLAUDE.md. Your AGENTS.md then stays at whatever revision it had — AGENTS.md-native engines keep reading that text while Claude Code follows the newer CLAUDE.md. Remove AGENTS.md itself (or paste its exact text into the portal) if you want SideButton to manage it again.

Verifying what a workspace deployed

On the VM:

ls -l ~/workspace/AGENTS.md ~/workspace/CLAUDE.md
cat ~/workspace/CLAUDE.md      # expect the marker + @AGENTS.md

From the portal API, per workspace — the agent reports the on-disk size and last-modified time of all three files, so you can confirm an apply actually landed. Authenticate with your account's API token (not an agent's SB_TOKEN, which this endpoint does not accept):

curl -s -H "Authorization: Bearer $SIDEBUTTON_API_TOKEN" \
  https://sidebutton.com/api/workspaces/$WORKSPACE_ID/git-status \
  | jq '.agents[].config_files'
# { "agents_md": {...}, "claude_md": {...}, "mcp_json": {...} }

The agents array is keyed off the workspace's git projects; a workspace with none reports an empty array, so add a project (or read the sizes on the VM) to verify one of those.

An agents_md whose size doesn't match the instructions you saved means the file was edited on the VM, or the apply never reached that agent. Save & apply re-syncs it.

Compatibility notes

• Agents upgraded from an older build keep working. Until an agent runs a build with AGENTS.md support, its instructions stay in CLAUDE.md and the portal reads the size from there. The next config apply after the upgrade converts the workspace — no migration, no downtime.
• Nested repos are untouched. SideButton writes only to the directories configured as entry paths — normally the workspace root. An AGENTS.md committed inside a project repo checked out below that is that repo's file and is never rewritten.
• Knowledge packs are unaffected. Domain packs are served over MCP as skill:// resources, not through the instruction file. See Knowledge Packs.