Claude Agent Teams in Zellij: Sessions and Handoffs

Zellij is a terminal multiplexer — a tool that splits a terminal window into panes and keeps sessions alive after a disconnect. When you run several Claude Code agents in parallel, Zellij gives each one its own visible pane, lets you watch them work at the same time, and recovers sessions if your SSH connection drops.

The limitation is that Zellij manages pane visibility, not task state. When an agent pane closes or a session ends, the task ownership and handoff notes live only in that chat context — unless they are saved somewhere external. Tools like fenbs keep task ownership and handoff notes outside the terminal so the next agent in any pane picks up from confirmed state.

How Claude agent teams use Zellij

A Claude agent team in this context means multiple Claude Code instances running in parallel — each on a separate task or subtask — coordinated by a parent agent or by you. Zellij suits this pattern because it lets you see all the agents at once in a single terminal window.

Each agent runs in its own pane. You can open a floating pane to issue an instruction to one agent without leaving the overview. When an agent finishes a task, you can scroll its pane to review the output before switching it to the next one.

The claude code subagents vs agent teams post explains the coordination models available. Zellij is infrastructure for visibility; it does not change how Claude Code agents themselves communicate or divide work.

Recommended pane layout for an agent team

1. Start a named Zellij session from your project root: zellij --session project-name. The name lets you reattach to the same session later without hunting for the right one.
2. Create one pane per agent task. Narrow tasks with clear boundaries — "implement the validation function", "write the unit tests for module X" — are safer to run in parallel than broad open-ended ones.
3. Keep a coordination pane. One pane at the top or side runs no agent; it is your view for checking git status, running tests, or issuing instructions across agents.
4. Name each pane for its task using Zellij's tab or pane naming. You will lose track of which agent is doing what when there are more than three running.
5. Set a pane to follow (scroll-locked) when you want to watch an agent's live output. Release the lock before switching focus so you do not miss input prompts from other panes.

Session persistence and recovery

Zellij keeps sessions alive after a disconnect, which is one of its main advantages over plain tmux for remote work. If your SSH session drops while an agent is running, reattach with zellij attach project-name and the agent's pane and output will be exactly as you left them — unless the agent itself exited.

Claude Code does not reconnect automatically to a dropped session. If the agent process exited during a disconnect, you will see its final output in the pane. Check what it completed and what it left half-done before starting a new agent on the same task.

• Check git status before starting a replacement agent. Partially completed edits may be uncommitted.
• Read the last lines of the agent's output to see where it stopped.
• If the agent was mid-task, give the replacement agent the current state explicitly rather than the original instruction.

Keeping handoffs visible between agents

The hardest part of running multiple agents in parallel is making sure each one knows what the others are doing without creating conflicts. Two agents editing the same file in parallel will produce merge conflicts. An agent that does not know another completed a prerequisite task will redo the work or skip a necessary step.

Assign each agent a branch that no other agent writes to. Before an agent starts, check that its branch is current with the work the other agents committed. Before calling an agent done, have it commit cleanly and record what it changed and what it left for the next one.

The coordination pane is where you review those commits and decide what comes next. Keep that decision in a place both the terminal session and future agents can see, not just in your memory.

How to do this with fenbs

1. Create a free account and add a project for the work the agent team is doing.
2. Break the work into tasks with clear scopes. Assign each task to one agent. Write what each task covers and what it explicitly does not cover.
3. Before starting each agent, have it read the fenbs project context: its task, the current Rules, and Where we left off. This gives it the boundary conditions before it touches any file.
4. Before each agent stops, have it save progress: what it completed, what it checked, and what the next agent on this task should start with.
5. In your coordination pane, review the task updates in fenbs before deciding what to run next. The history log shows you what each agent did and when.

For team-level task management and roles, see claude projects for teams and claude team plan.