AgentGridAgentGrid Docs
Core Concepts

Spaces and project folders

Each space binds to one project folder, the working directory for new agents and terminals.

A space is a top-level AgentGrid workspace. It appears as a tab, owns a canvas and its pane layout, and binds to one project folder on disk.

Set the project folder

Choose a recent project from the empty-space picker, browse for an existing folder, or create a new folder from the native picker. You can also drag a folder from Finder, Explorer, or your file manager onto the canvas. AgentGrid stores the selection as the space's project folder; choosing or dropping another folder updates the binding.

To open the folder itself, right-click the space's tab and choose Open in Finder (or Open in Explorer on Windows, Open in File Manager on Linux).

A space without a project folder can still hold notes, titles, browsers, and media. Anything that needs a working directory asks you to select a folder first.

What the folder controls

  • New terminal and harness panes start in that directory.
  • Typing /resume in an agent opens Resume a session, which can narrow its list to This folder or This branch.
  • Custom roles and notes resolve from its .agent-grid/ directory.
  • A worker normally inherits its master's working directory; the master can give a worker a different cwd when needed.

Changing the folder does not restart existing panes. Running terminals and agents keep their original directory; only panes created afterward use the new binding.

Project settings

Right-click a project tab or an empty spot in the Workspace Explorer, and choose Project Settings… to open Project Settings for that project, its own window with the project's name in the title. It holds only the pages a project can override: Agents, plus browser JavaScript under Advanced, observability and Lab. Settings itself always shows your global settings; a setting that an open project changes for itself names that project there ("agent-grid sets its own"), and clicking the name opens that project's Project Settings. Overrides are saved on this device. On Agents, the default agent, accounts and permission mode share a general group, and each agent's model, effort and speed defaults are grouped under that agent's name. A setting that follows your app setting usually shows its value and Set for this project; one from the repo says From the repo, and an override says This project. Choose Set for this project to keep a value locally. An override offers Reset to app setting or Reset to repo setting, naming the layer it will inherit again. A project with no overrides uses your global settings.

The project's Agents page sets how its agents start:

  • Default agent picks the agent new team leads start with. The spawn menu, number shortcuts, new-agent shortcut, command palette and Fix with agent list it first.
  • For an agent with more than one usable account, choose the account it starts on in that project.
  • For each agent, set the project's default model, effort and speed. Workers, and team leads in a conversation pane, started in the project use them. Reset goes back to your choice in Settings → Agents.

If the project allows only some agents or models, the spawn menu, shortcuts, palette and Fix with agent never offer a blocked agent, and a model the project doesn't allow is never its default.

Browser JavaScript changes, and turning Lab off, apply to the project's agents straight away, including ones already running. Turning Lab on and observability changes apply to agents started afterward; restart a running agent to give it Lab tools.

Project database (experimental)

AgentGrid keeps each project's canvas in files in its .agent-grid/ folder. To keep new projects in a database in your AgentGrid profile instead, sign in and turn on Settings → Advanced → Project database (experimental), then restart AgentGrid. It's off by default. If AgentGrid last closed unexpectedly and left its background service running, that service is restarted to apply the change, which stops its terminals and agents. Only projects you create afterwards go into the database; projects you already have stay on files. Turning it off again keeps your database projects working. To bring one back to files, open it and choose Export to files under Settings → Advanced → Move out of the database.

After turning it on, don't go back to a version of AgentGrid older than 2.8.2: database projects look empty there. Nothing is lost, and updating again brings them back.

One folder per space, many spaces per project

A space points to one folder, but several spaces can point to the same project. This is useful when you want separate build, review, and investigation canvases over one repository.

AgentGrid remembers recent projects so you can rebind a space without browsing from the filesystem root each time.

Share a project across devices

Pair two desktops under Settings -> Devices -> Advanced, and the second can open the host's recent projects (up to the last 10), plus any project shared from it earlier, under Open Remote Project. Open Remote Project on the start screen opens a window that lists your computers first; pick one to see its projects. A headless server opens over the AgentGrid relay, which needs AgentGrid Pro; if this desktop was signed in before 2.9.60, it asks you to sign in to AgentGrid once more first. A computer that this desktop can't reach yet is shown greyed out, and paired computers that aren't on your account appear under Paired computers. There is no per-project share step. The same page lists what this computer offers under Shared projects, and the computers you can reach under Computers you can access. Connecting computers needs Keep workers and terminals running in the background turned on under Settings -> Advanced on both of them, followed by a restart.

For the full walkthrough, see Shared projects.

Next

On this page

Ask AI

Ask a question about AgentGrid. Answers come from these docs, with links to the pages they use.

AI answers can be wrong. Check the linked pages.