Terminal multiplexers like tmux and screen were built for humans who need to juggle multiple shells, detach from remote sessions, and resume work later. Corgi takes the same concept and adapts it for agents that need to share a shell environment, switch contexts between tasks, and hand control back to a human when they get stuck.
The core problem: agents need persistent sessions, isolated command history, and a way to signal when they need help. Traditional multiplexers do not track which agent ran which command, cannot replay file changes per workspace, and have no concept of token usage or agent state. Corgi adds those layers on top of the familiar multiplexer pattern.
Architecture: Multiplexer Plus Agent State
Corgi runs as a persistent daemon that manages multiple terminal sessions. Each session can host a human, an agent (Claude, Codex, Pi, or others), or a long-running process like a dev server. The daemon tracks:
- Session state: which agent is active, what it is doing, and whether it needs human input.
- Command history: isolated per workspace, preventing one agent’s history from polluting another’s.
- File changes: the site advertises a replay feature that displays “every file it touched, in one scroll.”
- Token usage: live tracking of which agent consumed how many tokens.
The multiplexer itself is built on top of modern terminal protocols. It integrates with Ghostty and Kitty to support image paste and link handling, letting agents and humans share rich content in the same shell.
Session Persistence
Like tmux, Corgi keeps sessions alive in the background. If you close your terminal or SSH connection, the agent keeps running. When you reconnect, you see the same state: command output, file changes, and agent status.
The site describes this as “keep ‘em running” and notes that “your agents and processes keep running in the background.” This is critical for long-running agent tasks like code generation or multi-step workflows.
If an agent process crashes, the session remains attached to the multiplexer daemon. You can inspect the last output, review the command history, and restart the agent in the same workspace. The daemon does not automatically restart crashed agents, so you need to handle recovery manually or script it through Corgi’s CLI.
Context Switching
Corgi lets you switch between agent sessions and human sessions with keyboard shortcuts. Ctrl-T opens a new tab or jumps to an existing workspace. Ctrl-Shift-T undoes a tab close, like a browser.
When you switch contexts, Corgi saves the current session’s working directory and command history. When you switch back, it restores them. The site shows a status bar that tracks multiple sessions (“terminal 1 · agent”, “terminal 2 · dev server”) and indicates which ones need attention.
The multiplexer also tracks which agent is “active” in each session. If an agent needs human input, Corgi marks the session as “needs you” and surfaces it in the status bar.
Likely Isolation Mechanisms
The feature descriptions suggest that agents share the same shell binary (bash, zsh, or fish), but Corgi isolates their state. The exact mechanism is not documented on the site, but the observable features point to:
- Command history: each workspace gets its own history file. The site mentions “activity tracking” that shows what each agent did.
- Working directory: each session has its own
cwd. Corgi tracks it and restores it when you switch back. - Process tree: long-running processes (dev servers, background jobs) stay attached to their session. Corgi does not kill them when you switch contexts.
This isolation is not a sandbox. Based on the feature set, Corgi does not appear to isolate the filesystem or network. If an agent modifies global state (like installing a package system-wide), other sessions see the change. The multiplexer assumes agents are cooperative, not adversarial.
Workspace Organization
Corgi organizes agent workspaces to prevent conflicts. The site mentions “worktrees” and shows that Corgi “organizes your workspaces for you.” Each agent gets its own workspace directory, allowing parallel work without branch collisions. When you start a new agent session, Corgi creates a workspace. When the agent finishes, you can review its changes before merging or discarding them.
Replay and Observability
Corgi tracks file changes per workspace. The site advertises a “replay” feature: “see their changes. Every file it touched, in one scroll.” When you hover over an agent in the status bar, you see what it did.
The replay log enables post-hoc debugging of agent decisions and supports code review workflows before merge. If an agent makes an unintended modification, you can see exactly what it did and when.
The replay log is stored per workspace. If multiple agents work in the same workspace, their changes are likely interleaved in the log.
Token Tracking
Corgi tracks token usage per agent. The site shows “top for your tokens” and asks “where did the tokens go?” You can see live token usage in the status bar or query it from the interface.
Token tracking provides cost visibility and helps identify expensive operations. If an agent is consuming tokens faster than expected, you can see which tasks are expensive and optimize them.
Token tracking requires integration with each agent’s API client. Corgi ships with integrations for Claude, Codex, and Pi. If you want to track tokens for a custom agent, you will need to instrument its API calls.
Human-in-the-Loop Handoff
Corgi marks a session as “needs you” when:
- The agent encounters an error it cannot recover from.
- The agent asks a question that requires human judgment.
- The agent finishes its task and is waiting for review.
The multiplexer surfaces these sessions in the status bar with a visual indicator. You can press F1 to “catch up” and jump to the next session that needs attention.
This handoff is manual. Corgi does not automatically pause an agent or block its execution. The agent decides when to signal for help, and the human decides when to respond.
CLI and Automation
Corgi exposes a CLI for scripting and automation. The site mentions “drive Corgi from any terminal” and shows that you can teach agents new skills with corgi --skill.
The exact CLI syntax is not documented on the landing page, but the feature set suggests you can create sessions, switch contexts, and query agent state from the command line.
Tradeoffs and Failure Modes
| Aspect | Benefit | Consideration |\n|--------|---------|---------------|\n| Session persistence | Agents survive disconnects and crashes | Stale sessions consume resources if not cleaned up |\n| Shared shell | Agents use familiar tools and scripts | No filesystem or network isolation; agents can interfere with each other |\n| Workspace per agent | Clean separation between agent tasks | Disk usage grows with number of active agents |\n| Manual handoff | Human stays in control | Agent can get stuck waiting for input if human is unavailable |\n| Token tracking | Cost visibility | Requires per-agent integration; custom agents need instrumentation |
Failure modes to watch for:
- Environment leakage: if an agent modifies global state (system packages,
/etcfiles), other agents see the change. - History pollution: if Corgi’s history isolation breaks under rapid context switches, one agent’s commands may appear in another’s history.
- Zombie sessions: if the daemon crashes and does not clean up, you can accumulate orphaned sessions that consume memory.
- Workspace conflicts: if two agents are assigned the same workspace name or try to work on the same files simultaneously, merge conflicts can block both.
- Replay log gaps: if Corgi misses file changes during a crash or restart, the replay log will be incomplete.
Technical Verdict
Use Corgi when:
- You are running multiple agents on the same machine and need to track what each one is doing.
- You want session persistence without building your own multiplexer.
- You need to review agent changes before merging them (the replay log supports this workflow).
- You are comfortable with agents sharing the same shell and filesystem (no strong isolation required).
Avoid Corgi when:
- You need strict sandboxing or security boundaries between agents (use containers or VMs instead).
- You are running agents in production and cannot tolerate manual handoffs (build automated recovery instead).
- You need to coordinate agents on the same files in real time (workspaces create separate directories, not shared state).
- You are working with agents that do not expose token usage or cannot signal when they need help (Corgi’s observability depends on agent cooperation).
Corgi is a good fit for local development and experimentation. It is not a production orchestration platform. If you need multi-tenant isolation, automated recovery, or distributed agent coordination, you will need additional infrastructure.
Corgi builds on work from the Ghostty and Kitty terminal projects (which provide the modern terminal protocol foundation), the herdr and herdr-reviewr tools (which inspired the multiplexer design), and Pi’s pi-tui library. Bun enabled Corgi to be written in TypeScript.