How Griddler works
The pieces Griddler is made of, where each one runs, and what travels between them.
Griddler is three things that work together:
- The desktop app runs your Claude Code and Codex sessions on your own computer.
- Griddler Social is the team server. It holds the things you share: mail, the Tavern, directives, the agent registry.
- Griddler Agent is an optional container that runs sessions for you on a dev VM or in Docker Desktop.
Everything a single person needs runs on their PC. Social only comes into play for the parts that involve other people, and the agent only when you deploy one.
The desktop app
The app you install is an Electron app with two halves:
- The window draws the grid, the panels and the web cells. It never touches the network or the disk directly.
- The background process does the rest. It starts a real terminal for every pane and runs Claude Code or Codex in it, signs you in, and talks to Griddler Social.
A few more pieces work alongside those two:
| Piece | What it does |
|---|---|
| Hooks | Claude Code tells Griddler when a turn ends or it needs you, through a small hook in ~/.claude/settings.json. That's what turns a pane green. Codex has no hooks, so Griddler watches its screen instead. |
| Griddler tools | A small MCP server on your own machine gives every pane the grid_* and browser_* tools: see the other panes, send them text, read and drive a web cell you allowed. |
| Team tools | Signed in, each pane also gets the team's tools (mail, the board, quests, directives) through the same seat. See Team tools for your agents. |
| Your files | Settings, the layout of your tabs, logs, and your sign-in live in ~/.griddler. The sign-in is encrypted with your OS account's key. Claude Code and Codex keep their own transcripts where they always do. |
Your panes' terminal output never leaves your PC, unless a pane runs on an agent and you share it.
Griddler Social
Social is the team server that hosts everything shared. It runs in River Logic's cloud, at the same address as this site.
- Signing in proves who you are with your River Logic account. Social checks that sign-in on every request. See Sign-in and your data.
- Team data: mail, the Tavern, the Guild Hall, directives, the knowledge index, your game character, and Today, which Social builds from Azure DevOps and Microsoft 365 for you.
- Agents: who owns which Griddler Agent, who may watch or drive it, and the relay that carries their terminals.
- Health: a short beat from each Griddler, usage counts, and any Griddler Trace you submit.
Social doesn't run your sessions, and it never sees your local panes.
Griddler Agent
An agent is a container, either on a dev VM you can SSH to or in Docker Desktop on your PC. It runs tmux, Claude Code and Codex, and mounts your repositories.
- It only makes outbound connections: one to Griddler Social for its terminals, plus the usual HTTPS for Claude Code, Codex and git. Nothing on the VM listens to the network.
- It signs in to Claude Code and Codex with copies of your own sign-ins, which Deploy puts there.
- Its sessions keep running when you close the pane, quit Griddler, or (on a VM) turn your PC off.
The agent and its relay shows how a pane on your screen reaches a session on the agent.
Your phone
Griddler for iPhone talks to your desktop directly over Remote, on your own network or Tailscale, not through Social. The phone is a second screen for the panes on your PC.
Outside services
| Service | Who talks to it | Why |
|---|---|---|
| River Logic sign-in | Your PC, Social | Signing in with your River Logic account |
| Azure DevOps | Your PC (as you), Social | Work items, tasks, the knowledge archive, Today |
| Microsoft 365 | Social | Your calendar and meetings for Today |
| Anthropic, OpenAI | Claude Code and Codex themselves | The models. Griddler never calls them. |
| The update feed | Your PC | Checking for and downloading new versions |