The .agent-grid folder

Every project folder you bind to a space gets an .agent-grid/ subfolder that Agent Grid 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/          # synced notes from this project's note panes
├── notes-inbox/    # drop a .md here → it becomes a note pane
├── roles.json      # custom role definitions (optional)
└── qa-specs/       # browser_qa workers' write area

notes/ — synced note panes

Every note pane on the canvas writes itself to <projectDir>/.agent-grid/notes/<slug>.md. The slug is derived from the note's title (or its first non-empty line if there's no title). Updating a note pane updates the file; the file is the durable copy.

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 on the canvas.

notes-inbox/ — drop a markdown file, get a note pane

Writing a .md file into <projectDir>/.agent-grid/notes-inbox/ is the supported way for any process — Claude, a script, you in your editor — to put a new note on the canvas.

The flow:

1. Write a markdown file to <projectDir>/.agent-grid/notes-inbox/meeting-notes.md.
2. Agent Grid polls the inbox every couple of seconds.
3. A new note pane appears on the active space's canvas. The filename (minus the .md and with dashes turned into spaces) becomes the title.
4. The source file in notes-inbox/ is deleted.

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 model — 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.",
    "model": "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.