Workspaces, projects and repos

Three levels. A workspace is a folder of code plus a config folder Grid Console owns. A project is one folder inside it. A repo is your repo, and Grid keeps its own files out of it.

Workspaces

A workspace is two paths: the working directory you pointed Grid at, which holds only your code, and ~/.grid/<name>, which holds everything Grid owns for it. Settings are per workspace; there is no global preferences file that changes another workspace's behaviour.

The roster lives in ~/.grid/config.json. The last workspace you chose opens on launch, and Switch workspace… in the top bar opens the roster: one card per workspace with its CODE and CONFIG paths, and a dashed ＋ New workspace card. Forget removes a workspace from the roster and never touches the code folder.

<name> is decided once, when the workspace joins the roster: lowercased, letters, digits, dots, dashes and underscores, at most forty characters. Two workspaces both called grid get ~/.grid/grid and ~/.grid/grid-2. A name that collides with Grid's machine-wide folders (contexts, models, plugins, runtime, config.json, active-port) is refused.

Where things live

Grid still writes two gitignored things into a checkout: .claude/settings.local.json, for the hooks that keep the board updated, and .run/, for the pidfiles and logs of apps it starts.

Projects

One folder, one project. Every folder directly inside the working directory is a project, named after the folder; a workspace with no projects yet adopts them at boot. Grid never looks inside a folder for checkouts, so a folder holding three repos is one project with three repos, and a folder with no .git at all is a project too. Build output and dependency trees (node_modules, dist, build, vendor, target) are skipped, as are names that read as a parked copy (api.bak, site-old). Pointed straight at a checkout, Grid makes one project called that. Nothing is wrapped or reorganised, and projects an older rule split apart can be folded back together from Settings.

Repos inside a project are found when a card needs a worktree, up to three levels down and at most eight per card unless the card names them. A project with no folder yet, or whose folder holds no git repository, runs its cards in place: there is no checkout to isolate from, and Grid says so in the log rather than refusing.

A project also names who its sessions run as: the provider account they bill to, or a pool of accounts to spread across, which outranks a single account. Both are checked against the registry, and a name it does not know is dropped rather than saved.

Commands: grid.toml

Grid runs a project's commands from exactly one file, and it owns it: ~/.grid/<name>/projects/<project>/grid.toml. An in-project grid.toml is not read. The first time a project's commands are asked for, Grid learns from the Makefile (APPS, CMD_<name>, PORT_<name>, start-<name>, test, deploy) and writes what it found there once. After that the file is the truth, and a Makefile that contradicts it is ignored. The edit… sheet on the project's COMMANDS group runs the same discovery as a dry run and writes nothing until Save. Only grid.toml and a Makefile are consulted; anything else you declare in the sheet.

[project]
verify = "make test"

[repo.api]
runner = "make"
start  = "cd api && go run ./cmd/server"
test   = "go test ./..."
port   = 4000
url    = "http://localhost:4000"

[repo.migrations]
run    = "none"
test   = "pwsh ./verify.ps1"
shell  = "pwsh"

Any other key or table is refused by name and line number, and a file that fails to load runs nothing.

Delivery, per project and per repo

The first card filed into a project asks for its delivery settings once at capture; the project's Settings tab holds them after that.

The engine also carries GitLab merge requests, an ask-first flag and a deploy mode (none, from this machine, or CI/CD) into every session's context; none of the three has a row in Settings yet. Whatever is set, nothing is committed or pushed until you approve the review.

Human approval

A project carries no autonomy setting. Whether a card stops for you at the plan and at the diff comes from its card type and from the GATES on its capture sheet (Skip plan approval, Skip human review); see cards. Rules per stage, overridden per card type and per project, are planned in workspace settings.

Schedule

A card can be parked until the plan's five-hour window resets, fired at a fixed local time, or set to recur daily or weekly, from the schedule control in its session. Per project, SESSIONS AT ONCE caps how many scheduled cards run at the same time (1, 2, 4, 6 or no cap); a due card whose project is full waits for the next tick. Limit agents, on the board's header, is the other cap: with it on, each column's header sets how many agents may be live in that stage across the whole workspace, and every start past that number is refused, scheduled or not. It is off by default, and the numbers it holds are kept and shown but refuse nothing while it is. Workspace-wide, PAUSES FIRST orders which projects stop taking scheduled work as the weekly plan fills, and PAUSE FROM says at what percentage.

Memory and context

Each project keeps four hand-editable markdown files under ~/.grid/<name>/projects/<project>/memory/: facts.md, decisions.md, runbook.md and environment.md. One ## heading per entry, the lines under it are the body, and anything before the first heading is preamble that survives a write. Two conventions ride in the heading: ## GOTCHA: in Facts marks a trap, and ## [off] in Decisions marks a rule no longer in force. The project's Memory tab shows the four files and adds, edits and deletes entries; every session reads them before it starts and is told what they are for: durable knowledge for the sessions after it (how the project runs, ships and deploys, decisions that hold from now on, traps), and told to keep what one card changed out of them. Nothing writes them on an agent's behalf; the agent writes an entry the moment it learns something, with grid memory write, and you edit the files or the Memory tab. grid memory on the command line writes over HTTP, so a card in a worktree writes to the project rather than to its own copy.

Grid writes no context file and asks for none. A session runs as an ordinary Claude Code session in its worktree, so it reads whatever CLAUDE.md you keep globally, in the working directory or in the project.