The .agent-grid folder
The per-project folder where notes and custom roles live.
Every project folder you bind to a space gets an .agent-grid/ subfolder that AgentGrid uses for project-local state. It's checked into source control if you want — none of it is secret — and it's the contract between you, your agents, and the app.
<projectDir>/.agent-grid/
├── notes/ # every note pane IS a .md file here
└── roles.json # custom role definitions (optional)notes/ — notes are files
Every note pane on the canvas is a markdown file at <projectDir>/.agent-grid/notes/<slug>.md, and the file is the source of truth:
- Write a markdown file to
<projectDir>/.agent-grid/notes/meeting-notes.md— any process can: an agent, a script, you in your editor — and a note pane appears on the canvas within a moment. The filename (minus the.md, with dashes turned into spaces) becomes the title. - Edit the file and the open note pane updates in place.
- Delete the file and its note closes. Undo with CmdZCtrlZ brings the note back, and if the file reappears the note does too.
- Edit the note in the app and the file is saved on pause, blur, or close.
- Drop a
.mdfile onto the canvas and it is copied intonotes/as a new note.
If the file changes on disk while you are still typing in the note, the file wins and the pane shows "Note updated from its file. Your unsaved typing was set aside." Click Restore on that message to bring your typing back. No extra copies are written to the folder.
Note panes check your spelling as you type. Right-click a misspelled word for suggestions or Add to Dictionary.
This folder is the right place to look for any note an agent or you authored in a space — the canonical text lives here, not in the app.
roles.json — your custom roles
.agent-grid/roles.json is a JSON object keyed by role name. Each entry can override or extend a built-in role (see Roles for the seven built-ins: builder, qa, validator, backend, frontend, devops, security). Project roles merge over the built-ins, so you can tweak one field — say, systemPrompt or models — without restating the whole config.
A minimal example:
{
"qa": {
"systemPrompt": "You are this project's QA reviewer. Run the test suite and report a verdict."
},
"release-manager": {
"systemPrompt": "You cut releases. Bump the version, write the changelog, open the PR.",
"models": {
"claude": "claude-opus-4.7-20251201"
}
}
}A role you define here is immediately available via the master's spawn_role MCP tool and shows up alongside the built-ins in list_roles.
Next
- Roles — full reference for the seven built-in roles.
- Notes guide — using the note pane day-to-day.