Getting started

Download the desktop app, sign in, point Grid Console at the folder your code lives in, and it lists your projects. The tour walks you over the live interface, and the demo project gives you a board full of cards to try decisions on before you file one of your own.

1. Install

Grid Console is a desktop app with its own local daemon inside; there is no server to run. Quitting the app stops the daemon too. If agents are still working when you quit, Grid asks whether to stop them or leave them running in the background; a stopped card picks its conversation back up the next time you open Grid. The alpha ships four builds from one tag.

Updates are checked from inside the app: a new version downloads quietly and a Restart to update chip appears in the top bar once it is staged. Grid never restarts itself.

On first launch the window shows a sign-in screen with a device code. It opens the licence server in your browser; approve there and the window signs itself in. Grid is free while the alpha lasts. Use a licence key instead is drawn but inert: keys arrive with the beta.

2. Pick a working directory

First run is one screen in two steps. Step one asks for a working directory: type a path, pick one from CHOOSE A FOLDER, or press Choose…. Grid scans it and shows DISCOVERED n as a row of chips, one per project, each with its git state.

Every folder directly inside the working directory is a project, named after the folder. Grid does not look inside for checkouts: a folder holding three repos is one project, and a folder with no .git is a project too. Nothing is moved, renamed or wrapped.

Step two is Agents and models: which agent runs the cards (a real probe of your PATH for claude and codex, plus a row for every provider a plugin contributes, so bundled copilot-provider makes three binaries on a stock install), the compute budget, and the model matrix that follows from it. Save and start the tour creates the workspace at ~/.grid/<name> and starts the tour; you can also skip it. With nothing to point at yet, Start with the demo seeds the demo project and carries on.

3. Let it configure the project

Grid runs a project's commands from one file, grid.toml, kept in Grid's own state at ~/.grid/<name>/projects/<project>/grid.toml and never in your repository. The first time a project's commands are asked for, Grid reads what a Makefile already declares (app names, commands and ports, start-<name>, test, deploy) and writes it there once. After that grid.toml is the truth; the keys are listed in Workspaces.

To see and change it, open the project in Settings and press edit… on the COMMANDS group, or use Project › Auto-configure… in the menu. Both open the same sheet: discovery runs as a dry run, every command it found is listed with where it came from, you edit what you like, and nothing is written until you press Save. Only grid.toml and a Makefile are read; anything else you declare in the sheet.

Grid writes no context file and requires none. A session started by Grid is an ordinary session of the provider you chose, running in the card's worktree, so it reads whatever CLAUDE.md you already keep. Verify steps that drive a browser need the Claude in Chrome pairing on this machine; the BROWSER row of the project's VERIFICATION group says whether it is there.

4. The tour and the demo

The tour is not a slideshow: it drives the real interface, highlighting one region at a time, in ten stops across Needs you, the backlog, Design, the Development board, the agents, the local environment, remote and CI/CD, the code, Projects, and sync and sharing. Replay it any time with ? or from the account menu.

The demo project is Mark Playground, a small visual app written to demo-mark-playground inside your working directory with its git history replayed, filed as the project demo. It carries twenty-four cards spread across the stages: a masterplan with ten subcards, a bug, a chore, a closed research card, and plain cards parked at the end of each stage with the artefact that stage produces, so Approve, Answer, Review and Rewind each have something real to act on. Nothing runs and nothing is billed; Insights stays at zero until you start something yourself.

If you skipped it, Settings offers or add the demo project under the project list. There is no reset or delete button for it; it is a folder and a project like any other.

5. Your first real card

Press ⌘N and describe the task. After three characters the right column fills in: the PROJECT guess, WHEN IT STARTS (straight away, or parked in Inbox), CARD TYPE, and the DIFFICULTY ladder from easy to vhard. WHAT THIS CARD WILL DO then shows, per stage, the model and effort the card will really run at, resolved through the workspace's budget and matrix, and NEEDS YOU says where the card type stops for you. There is no model picker. The first card in a project offers, once, how its work should land (Push the branch, Push the branch, open a PR, Merge, don't push or Merge, then push) and whether each repo gets a branch per card; the answers become the project's delivery settings. Skip it and the first card to reach Deliver asks instead.

Then the loop, as described in Cards:

• Prepare runs in the shared checkout, reads the code and writes the plan on the card. Questions come as pickers in the session; Grid only pings you that one is waiting.
• Approving the plan cuts grid/<slug> from the base the card recorded (the default branch, freshly fetched, unless the card pinned another), copies the project's seed files in, and hands the card to a fresh agent in Doing. The conversation does not carry over; the card body is the handoff. See Worktrees.
• Doing builds and writes a Review section. You approve, revise or reject, and Deliver, Verify and Close follow the project's delivery settings.

A new card stops for you at the plan and at the review. The capture sheet's OVERRIDES can skip either gate for one card, and a Chore's plan is pre-approved; see cards.

Settings you will meet on day one

There is no OS sandbox around a session: it runs with whatever your own Claude Code would use in that worktree, and Grid only refuses writes to your real checkout, your credentials and its own state. See Security.