Workspaces, projects and reposThree levels, and only one of them is opinionated. A workspace is a separate Grid Console. A project is a folder with repos beneath it. A repo is just your repo.WorkspacesA workspace is a wholly independent instance: its own config folder, projects, settings, memory, plugins, keymap and licence check. You choose the workspace when you open Grid Console, the way you choose which application to launch. Nothing is shared between workspaces and nothing leaks across, which is what makes client work and personal work safe to keep apart.WHEREWHAT LIVES THEREYour code folderYour repositories, untouched.~/.grid/<name>Settings, keymap, plugins, licence token.<config>/cards/One markdown file per card, plus its plan.<config>/worktrees/Per-card git worktrees.<config>/reports/Shift reports as markdown.<project>/grid/memory/Project memory, in the repo parent so it can be committed if you want.
Settings are per workspace, deliberately. There is no global preferences file that quietly changes how another workspace behaves.ProjectsA project is the unit everything else hangs off: cards, memory, autonomy, the board filter. On disk it is a parent folder with one folder per repository, plus whatever that project already uses to run its commands. Nothing else is required.northwind/ # the project api/ # repo 1 web/ # repo 2 infra/ # repo 3 grid.toml # optional: commands, when discovery is not enough CLAUDE.md # optional: generated context, improves agent quality grid/memory/ # optional: facts, decisions, runbook, environment
Why the parent folder? Because a card often spans repositories, and a worktree needs somewhere to live that is not inside one of them. That is the whole of the opinion: one folder, repos beneath it. How commands run is discovered, not dictated, and the context file is generated, not demanded.How Grid Console runs your commandsGrid Console does not care how a repository builds, tests or starts. It cares that it can ask. On first open it looks for a command interface in each repo folder and stops at the first it finds:WHAT IT LOOKS FORNOTESgrid.tomlExplicit, optional, and wins over everything else. Written for you if you accept the suggestion at setup.Makefile · justfile · Taskfile.ymlUsed as-is if a matching target exists. Never generated on Windows.package.json scriptsPlus composer.json, pyproject.toml, Cargo.toml, *.csproj, build.gradle, go.mod.docker-compose.yml · DockerfileFor repos whose only reliable local run is a container.Nothing foundGrid Console asks once, per repo, and writes the answers to grid.toml. It never invents a build system for you.
Windows is a first-class target: make is often absent there, so npm scripts, Taskfile or a plain PowerShell line carry the same contract. Each command may declare its own shell.grid.tomlOne file, per project, optional. Repos are sections; commands are strings. Anything you leave out stays discovered.[repo.api]test = "go test ./..."start = "go run ./cmd/server"lint = "golangci-lint run"[repo.web]test = "npm test"start = "npm run dev"url = "http://localhost:5173" # what Review links you to[repo.migrations]run = "none" # nothing to start, and that is finetest = "pwsh ./verify.ps1"shell = "pwsh"
What each command is used forCOMMANDWHEN GRID CONSOLE CALLS ITstartReview, to run the app locally and put the URL on the card.testVerify, and whenever a card claims a test passes.lintDoing, before the agent declares itself done.buildDeliver, if the delivery needs an artefact.check (project level)Close, one last sweep across the whole project.run = "none"A legitimate answer. A migration set or a library has nothing to start, so Review skips the local-run step instead of failing.Missing and undeclaredGrid Console asks you once and remembers, rather than guessing and reporting a false failure.
Context files and memoryA context file is optional. Grid Console runs without one; what it buys you is agent quality, so it is offered, not enforced. Accept Auto-configure project and it writes one: what the project is, which repos it contains, how to run and test each one, and how the stages work so the agent knows what a plan or a review means here. Decline it and Prepare simply asks more questions per card. The file name follows the active provider (CLAUDE.md for Claude Code, AGENTS.md or GEMINI.md for others), and it is a normal file in your repo parent, so you can edit it, diff it and commit it. Settings shows a plain Context: none · generate row so its absence is visible without blocking anything.Memory is separate and structured into four tabs, all plain markdown under grid/memory/: Facts (stable truths about the project), Decisions (what was chosen and why), Runbook (how to do recurring things) and Environment (ports, services, credentials layout, never secrets). Close writes to memory; you can edit any of it by hand.ALPHAAuto-configure and memory writing work today, and both are optional. Command discovery covers Makefile, justfile, Taskfile, npm, Composer, Python, Cargo, Gradle, Go and Docker Compose; anything else you declare once in grid.toml. Multi-repo discovery assumes the parent-folder layout; loose repositories are offered a wrapper folder rather than being reorganised silently.