| name | claude-pods |
| description | when managing Claude Pod terminal layouts - opening, closing, listing, or reopening Ghostty development environments with Claude Code instances, lazygit, and utility panes |
| version | 1.0.0 |
Claude Pods
Managed Ghostty terminal layouts for Claude Code development environments.
Core principle: A Claude Pod is a reproducible, stateful development environment. Open it once, close it, reopen it later — your Claude sessions, layout, and workspace assignment are always tracked.
When to Use
Invoke this skill when the user wants to:
- Open a new Claude Pod (development terminal layout) for a project directory
- Add a Claude Pod as a tab to an existing Ghostty window
- Close, list, or check status of Claude Pods
- Reopen one or all previously closed Claude Pods
- Move a Claude Pod to a specific workspace
What is a Claude Pod?
A Claude Pod is a Ghostty window (or tab) with this exact layout:
+-------------+--------------------------+-------------+
| Claude | | |
| Code 1 | | lazygit |
| (newest) | | |
+-------------+ | |
| Claude | +-------------+
| Code 2 | Main Pane | |
| | (full height) | |
+-------------+ | Utility |
| Claude | zsh prompt | Shell |
| Code 3 | | (zsh) |
| | | |
+-------------+ | |
| Claude | | |
| Code 4 | | |
| (oldest) | | |
+-------------+--------------------------+-------------+
Left col Middle col Right col
4 Claude Full-height zsh lazygit + zsh
- Left column (4 panes): Claude Code instances, resuming the 4 most recent sessions for that directory. Most recent session at the top.
- Middle column (full height): Open zsh prompt for running servers, tailing logs, etc.
- Right column (2 panes): lazygit on top, utility zsh prompt on bottom.
- All panes share the same working directory.
Prerequisites
This skill requires the following tools to be installed:
- Ghostty terminal emulator (macOS)
- yabai window manager (
brew install koekeishiya/formulae/yabai)
- lazygit (
brew install lazygit)
- Claude Code CLI (
claude)
The skill's scripts live at {skill_root}/../ (the repo root).
IMPORTANT: Hands-Off Protocol
Pod creation uses AppleScript to send keystrokes to Ghostty. A 3-second floating countdown appears before any keystrokes are sent. The user MUST take their hands off the keyboard during pod creation. Always warn the user:
"I'm about to open a Claude Pod. A countdown will appear — please take your hands off the keyboard until it completes."
Operations
Open a Pod
bash {skill_root}/../claude-pod.sh open --dir <path> [--workspace <N>] [--tab] [--delay <seconds>]
Standalone window (default): Creates a new Ghostty window with the pod layout.
bash {skill_root}/../claude-pod.sh open --dir ~/code/myproject --workspace 7
As a tab: Adds the pod as a new tab to the Ghostty window on the specified workspace.
bash {skill_root}/../claude-pod.sh open --dir ~/code/myproject --workspace 3 --tab
Tab mode validation:
- If 0 Ghostty windows on the target workspace: errors
- If 1 Ghostty window: uses it
- If >1 Ghostty windows: errors with "Multiple Ghostty windows on workspace N"
If --workspace is omitted, the pod is placed on the user's current workspace.
Close a Pod
bash {skill_root}/../claude-pod.sh close --workspace <N>
bash {skill_root}/../claude-pod.sh close --dir <path>
bash {skill_root}/../claude-pod.sh close --id <pod_id>
Marks the pod as inactive in state. The Ghostty window is not force-closed.
List Pods
bash {skill_root}/../claude-pod.sh list [--active|--inactive|--all]
Shows tracked pods with their directory, workspace, and mode.
Check Status
bash {skill_root}/../claude-pod.sh status
Prunes pods whose Ghostty windows no longer exist, then shows active and inactive pods.
Reopen a Pod
bash {skill_root}/../claude-pod.sh reopen --dir <path>
bash {skill_root}/../claude-pod.sh reopen --id <pod_id>
Reopens a previously closed pod with the same directory and workspace. Discovers the latest Claude sessions for that directory.
Reopen All Pods
bash {skill_root}/../claude-pod.sh reopen-all
Reopens every inactive pod. Useful after a Ghostty restart or system reboot.
Natural Language Examples
Users will say things like:
| User says | Command |
|---|
| "Open a Claude Pod for ~/code/breenix on workspace 7" | open --dir ~/code/breenix --workspace 7 |
| "Add a pod tab for ~/code/penpot on workspace 3" | open --dir ~/code/penpot --workspace 3 --tab |
| "Open a pod here" | open --dir <cwd> |
| "Close the pod on workspace 5" | close --workspace 5 |
| "What pods are running?" | list --active |
| "Reopen all my pods" | reopen-all |
| "Reopen the breenix pod" | reopen --dir ~/code/breenix |
State Management
Pod state is persisted at ~/.claude-pods/state.json. Each pod tracks:
- Unique pod ID
- Working directory
- Workspace number
- Mode (standalone or tab)
- Ghostty window ID
- Claude session IDs (for the 4 left-column panes)
- Active/inactive status
The state file enables pod lifecycle management across Ghostty restarts.
Error Handling
| Error | Cause | Action |
|---|
| "Multiple Ghostty windows on workspace N" | Tab mode with ambiguous target | Ask user which window, or use standalone mode |
| "No Ghostty windows on workspace N" | Tab mode with no target | Fall back to standalone mode on that workspace |
| "Ghostty lost focus" | Something stole focus during layout | Retry — the layout script checks focus before each keystroke |
| "No matching active pod found" | Close/reopen with bad identifier | Run list --all to show available pods |
Tips
- Pod creation takes ~8-10 seconds. The countdown gives you 3 seconds of warning before it starts.
- If a layout comes out wrong (missed split), close the window and reopen the pod — the session IDs are preserved in state.
- The
status command automatically prunes pods whose windows have been closed manually.
- Session resume uses
claude --resume <id>. If a session is very old, Claude may need a moment to load it.
