Sessions & agents

Each pane runs one agent or shell, in its own working directory and process group.

Creating a session

Press ⌘N (or + NEW) to open the new-session dialog. Pick:

  • Agent — Claude, Codex, Gemini, Cursor, or a shell.
  • Project folder — the working directory. Browse local folders or clone a GitHub repo right from the dialog.

+ SAME opens another session of the focused agent type in the same project — one keystroke to fan out.

Agent types

  • claude — Claude Code. Supports --resume to continue a prior conversation.
  • codex — OpenAI Codex.
  • gemini — Gemini CLI.
  • cursor — Cursor's cursor-agent (falls back to cursor).
  • Shell — your $SHELL, for builds, tests, servers, git, anything.

Git worktree isolation

When you open a second agent in a repo another session is already using, CodeGrid can spin up a dedicated git worktreeon its own branch — so parallel agents never step on each other's changes. The pane shows its branch in the status bar.

TIP
Worktrees make "three agents on the same repo at once" safe — each commits to its own branch, and you merge when ready.

Status

Every pane reports a live status, surfaced in its tab and the global attention bar:

  • running — actively producing output.
  • idle — quiet / waiting (a finished run goes idle).
  • waiting — needs your input (a prompt was detected).
  • error / dead — errored or the process ended.

See Notifications & attention for how CodeGrid pings you when an agent finishes or needs you.

Rename, restart, close

  • Rename — double-click a tab (or right-click → Rename). Names persist.
  • Restart — a dead pane offers Restart to relaunch the agent in place.
  • Close — ⌘W terminates the session's whole process group (the agent plus anything it spawned, like dev servers), so nothing is orphaned.

Persistence

Sessions are saved per workspace and restored on next launch, with their layout positions intact.

Previous← The canvasNextWorkspaces →