The .agent-grid folder

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)
└── qa-specs/       # browser_qa workers' write area

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:

1. 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.
2. Edit the file and the open note pane updates in place.
3. Edit the note in the app and the file is saved on pause, blur, or close.
4. Drop a .md file onto the canvas and it is copied into notes/ as a new note.

If a file changes on disk while the pane holds unsaved edits of yours, nothing is overwritten: the competing version is preserved as a .conflict- sibling in the same folder and the pane tells you where it went.

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 eight built-ins: builder, qa, validator, backend, frontend, devops, security, browser_qa). 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.

qa-specs/ — the browser_qa write area

browser_qa workers are constrained to writing inside <projectDir>/.agent-grid/qa-specs/. This is the only path they're supposed to touch on disk — recordings, regression specs, and structured findings land there.

Next

• Roles — full reference for the eight built-in roles.
• Notes guide — using the note pane day-to-day.