Architecture

Both roles run from the same WASM binary and request the same seven Zellij permissions on load. The list lives in one place in the plugin (REQUIRED_PERMISSIONS in lib.rs), and the Go CLI seeds the identical list into Zellij’s permissions.kdl cache. A test in the CLI keeps the two lists the same.

Zellij caches grants by plugin URL, so the dialog the sidebar shows is what grants the background controller. The controller itself never sees a dialog. It runs from load_plugins, and Zellij cannot show a permission prompt for a plugin that has no pane (zellij-org/zellij#4982). A grant given to the sidebar also does not reach a controller that is already waiting (zellij-org/zellij#4990 is open). A cached grant is therefore the only way the controller starts on a first run.

cc-deck config plugin install seeds the cache and fails if it cannot. Every workspace launch runs the same check again before Zellij creates the session, so a cache that was cleared in between is repaired instead of stranding the controller until the next restart. The check is idempotent and writes nothing when the entry is already correct.

Seeding alone is not sufficient. Zellij addresses the PermissionRequestResult event to a specific client, and a plugin started during the initial layout load can be handed that result before any client is ready to receive it. The grant is then dropped in transit. Both roles therefore recover from a timer: a plugin that is still unpermissioned when a timer fires asks again and re-arms the timer. The retry is bounded by PERMISSION_RETRY_LIMIT, and a denied result stops it at once, so a request that is genuinely waiting on a human answer is never re-raised on a loop. On a healthy start the grant has already arrived, the first tick returns early, and the recovery costs a single timer tick.

Zellij places one plugin pane in every tab, so there is one sidebar instance per tab and the number of instances grows with the number of tabs. The design keeps those instances thin. The controller is the single writer of session state. It processes hook events, pane and tab updates, and the timer, and it persists state to a per-session file in the plugin cache. Sidebars hold no session state of their own. They receive a pre-computed render payload, draw it, and send user actions back to the controller.

cc-deck requires Zellij 0.45.0 or later. Earlier releases could instantiate a load_plugins background plugin twice on startup (zellij-org/zellij#5178), and the plugin relies on there being exactly one controller per session.

The pipe messages between the two roles:

Claude Code hooks (configured in ~/.claude/settings.json) call the Go CLI on session events. The CLI forwards these to the WASM plugin via Zellij’s pipe system.

The flow:

Step 3 matters because zellij pipe succeeds when it is run from outside a Zellij session and delivers to whichever session is running. Without that check, an agent started in a plain terminal would appear in the sidebar of an unrelated session.

A pane ID arriving on a hook event is a claim that the controller has not yet verified. The controller therefore holds a newly created session back until the Zellij pane manifest confirms that the pane exists, and removes the session if that confirmation does not arrive. This matters because pane IDs restart from zero in every Zellij run. An ID carried over from an earlier run does not simply fail to match. It addresses a different pane that is genuinely in use.