Collaboration

taiku sessions are multiplayer by default. This guide covers how that works in practice: focus, shell ownership, adoption, and what state is shared between participants.

The focus model

Every participant can navigate the workspace freely. Multiple people can type into different terminals at the same time without interfering with each other. The important question is what happens when two people want to type into the same terminal.

taiku resolves this with a focus lock. When someone is actively focused on a terminal and typing into it, that terminal is locked to their input. Other participants can see the terminal's output updating in real time, but their keystrokes will not be sent to it. This prevents the chaotic experience of two people typing into the same shell simultaneously.

The focus lock is lightweight and transient. It simply reflects who is currently interacting with the terminal. If someone stops typing and you click into the terminal, focus transfers naturally.

There is one exception to the focus lock: shell owners can always type into their own terminals, even when someone else has focus. This is a deliberate design choice. If you created a terminal and someone is watching it via peek or has navigated to it, you should not be locked out of your own shell. Ownership overrides the focus lock. See the ownership section below for more detail.

When focus conflicts happen

In practice, focus conflicts are rare in well-organized sessions. The typical patterns are:

• Each person works in their own terminals. This is the most common case. You create the terminals you need, your colleague creates theirs, and you work in parallel.
• One person drives, others watch. During pair programming, one person types while the other observes. The observer can peek at the terminal or scroll its history without interfering.
• Explicit handoff. When you want to take over someone's terminal, you use the adoption flow (covered below) rather than fighting over focus.

If you find yourself in a session where focus feels contentious, that is usually a signal to split the work across more terminals or use separate workspaces to separate concerns.

Peeking

The peek panel is taiku's mechanism for observing someone else's work without taking control. It provides a zoomed, read-only view of any terminal in the session, along with drag-to-pan navigation and full scroll history access.

Open the peek panel from the workspace UI when you want an overview of the session. The panel shows all terminals in the session, organized by shell owner. You can see:

• A live preview of each terminal's current output, updating in real time.
• Which terminals are owned by which participant.
• Which terminals have active AI agents (Claude, Codex, OpenCode) running in them, with status indicators.
• Activity indicators showing which terminals have recent output.

Clicking a terminal in the peek panel opens a full-size read-only view. You can scroll through the terminal's history, select and copy text, and drag to pan around, but you cannot send keystrokes to the terminal.

Peek is especially useful in a few scenarios:

Monitoring a colleague's progress. During pair programming, the navigator can peek at the driver's terminal to follow along without needing the driver to share their screen or explain what they are looking at.

Watching long-running processes. Open a peek view of the terminal running your test suite or deployment. You can continue working in your own terminals while keeping an eye on the output.

Reviewing agent activity. When AI agents are running commands in the session, peek provides a non-intrusive way to monitor what they are doing across multiple terminals simultaneously. The agent detection system identifies the agent type and shows its current status (thinking, running, idle) directly in the peek panel.

Orienting yourself in a busy session. If you join a session with many terminals and participants, the peek panel gives you an overview of what is happening across the entire session before you dive into a specific terminal.

Peek is available to both write-access and read-only participants. Read-only viewers can peek at any terminal in the session, making it especially useful in the --enable-readers scenario where viewers need to observe but not interact.

Shell ownership

Ownership is the core mechanism that makes multi-user terminal sessions predictable rather than chaotic.

When you create a terminal in a taiku session, you own it. Your ownership is tracked in the browser's local storage, which means it survives page refreshes and reconnections. As long as you return from the same browser, your ownership is preserved.

Ownership gives you specific privileges over your terminals:

1. You can always type into your own terminals, regardless of who else has focus on them. The focus lock does not apply to owners.
2. You can resize your own terminals at any time. Other participants cannot resize terminals they do not own.
3. Your ownership is visible to everyone. Other participants can see which terminals belong to you in the peek panel and in the workspace UI. This legibility is important: when people can see who owns what, the session feels organized rather than contested.
4. Your terminals appear in your workspaces. The workspace system groups your owned terminals together, making it easy to build layouts around your work.

Ownership is deliberately tied to the browser rather than to a user account. This means that if you open the same session in two different browsers, each browser has its own ownership context. Terminals you create in one browser are not automatically owned in the other. This is intentional: it prevents confusion in scenarios where multiple tabs or devices are involved.

Why ownership matters

Without ownership, every terminal in a shared session would be first-come, first-served for input. The first person to click into a terminal would get focus, and anyone else who wanted to type would have to wait. That model works for a single terminal, but it falls apart when a session has many terminals and many participants.

Ownership creates a clear default: you control what you created. Other participants can see your terminals, peek at them, and request adoption, but cannot accidentally take them over.

Adoption

Sometimes you need to take control of a terminal that someone else owns. Maybe your colleague stepped away and you need to continue their work. Maybe a student needs the instructor to take over and demonstrate something. Maybe an AI agent finished its task in a terminal and a human needs to pick up where it left off.

taiku handles this through an explicit adoption protocol. The flow works like this:

1. Request. You navigate to a terminal you do not own and request adoption. This sends a message through the session's chat channel (using a hidden protocol prefix that does not appear in the chat UI).

2. Prompt. The current owner sees a prompt in their browser: "Alice is requesting control of shell 3. Allow or deny?" This appears as a toast notification that requires an explicit response.

3. Approve or deny. The owner clicks "Allow" or "Deny". If they approve, ownership transfers to you immediately. Your browser's local storage is updated, and you can now type into and manage the terminal as your own. If they deny, nothing changes.

4. Completion. Both participants see the result. If approved, the new owner's workspace updates to include the adopted terminal. The previous owner's workspace removes it.

The adoption protocol uses the same channel as the chat system, which means adoption works across browsers and across network boundaries without any additional infrastructure. The same pattern extends to tunnel ports, where you can request access to a tunnel that someone else created.

When to use adoption

Adoption is the right tool when control needs to change hands explicitly:

• Pair programming rotation. After driving for a while, you hand the terminal to your pair partner. They request adoption, you approve, and they continue where you left off.
• Teaching. The instructor takes over a student's terminal to demonstrate a concept, then the student adopts it back.
• Incident response. The on-call engineer owns the terminals. When a specialist joins to help, they adopt the relevant terminal rather than creating a new one and losing the context.
• Agent-to-human handoff. An AI agent finishes its work in a terminal. A human adopts the terminal to review the output, run tests, or continue the task.

Presence events

taiku tracks participant presence at the session level. When someone joins or leaves, the host's CLI outputs a log line:

[connect]    alice joined
[disconnect] bob left
[session]    alice created shell 2

These events are also visible in the browser UI through avatar indicators in the toolbar. Each participant gets a colored avatar, and you can see who is currently connected, who has focus on which terminal, and who is idle.

Presence information flows through the WebSocket connection and is updated in real time. When a participant's browser disconnects (they close the tab, lose network, or navigate away), the server waits briefly for a reconnection before broadcasting a disconnect event. This prevents flicker from momentary network blips.

Shared state model

A taiku session shares more than terminal bytes. The full list of synchronized state includes:

Terminal content. All terminal output is encrypted and streamed to every connected participant in real time. Scroll history is available up to the server's buffer limit (2 MiB per shell).

Pane layout. The tiling layout of the workspace (splits, ratios, tile positions) is tracked and can be rehydrated when you reconnect or open the session in a new browser. Other participants can see your layout through the peek panel.

Shell ownership. Ownership assignments are broadcast to all participants so that everyone can see who owns which terminals.

Adoption state. Pending adoption requests, approvals, and denials are coordinated through the session channel.

Tunnel visibility. Active tunnels (port forwards) are visible to all participants. Tunnel tiles can be opened in any participant's workspace.

Plugin panels. Active plugins and their state are shared across the session, allowing all participants to see and interact with the same plugin panels.

User presence. Names, focus state, and connection status are broadcast to all participants.

Chat messages. The chat sidebar is shared across all participants in the session. Messages persist for the lifetime of the session.

This shared state model is what transforms taiku from a screen-sharing tool into a collaborative environment. Each participant has their own workspace layout (their own arrangement of terminals, tunnels, and plugins), but they share the underlying session state. You can see what others are doing, take over when needed, and work in parallel without stepping on each other's toes.

For how to organize this shared environment with workspaces and tiling, continue to Workspaces and Window Management.