Claude Code Workspace

The terminal workspace nexus run opens for Claude Code projects, configurable per user and per project.

Since v0.15.0, the Zellij workspace around Claude Code is built from workspace profiles: a preset defines the panes, tabs and sizes, a project can pick a team default, and every user can adjust panels, sizes and Zellij behavior for themselves. Requires nexus-cli 0.28.7 or later.

Overview

A project selects its AI tool (the executioner) in the project form: OpenCode or Claude Code. For Claude Code projects with the Claude Code Experience enabled, nexus run starts a Zellij workspace instead of a bare terminal:

• exactly one Claude Code pane; ending Claude Code ends the workspace and prints the session summary
• a sidebar with token usage, the agent observer and, in the default preset, a terminal
• extra tabs such as GIT (lazygit), TEST and LOGS

The layout is stored as a multiplexer-neutral model and rendered to Zellij KDL for each user. The renderer guarantees the invariants (one Claude pane, managed-file marker, escaped strings) and lists the host tools the layout needs (requires, for example zellij, lazygit, ccusage, node).

Use nexus run --plain to start Claude Code without the workspace, or --workspace to force it.

Presets

lazygit lives only in the separate GIT tab. When a layout contains the usage panel, requires lists node and the exported devbox.json gets a Node.js package if none is present.

Which preset applies

The workspace for a user is resolved in this order:

1. the user's own preset pick (My Settings > Workspace Profiles)
2. the project's team default
3. the system default (Standard + Terminal)

Set the team default in the project form's Claude Code Experience panel or from the CLI:

nexus env set claude.workspace_preset=focus

Personal settings

Under My Settings > Workspace Profiles, every user can:

• pick a preset
• switch panels and tabs on or off: Agent observer, Usage, Git (lazygit), Tests tab, Logs tab (switching Git on for a preset without a GIT tab adds one)
• change pane sizes
• paste a custom Zellij layout (advanced)
• see the rendered preview, the effective model and the generated KDL with line numbers

Only deviations from the preset are stored. Reset removes the personal settings and returns to the preset.

Changing a preset or a custom layout takes two steps: Validate runs the server-side validation and shows errors or the rendered preview; Save is enabled only for exactly the validated content.

Zellij settings

My Settings > Workspace Profiles > Zellij settings holds personal Zellij options:

nexus pull writes them to .nexus/claude/zellij.local.kdl, and nexus run starts the workspace with:

zellij --config .nexus/claude/zellij.local.kdl --layout .nexus/claude/workspace.local.kdl

• While any setting is set, this file replaces your global ~/.config/zellij/config.kdl for nexus run (Zellij has no include or merge). Options you leave unset keep the Zellij defaults, not your global values.
• An explicit ZELLIJ_CONFIG_FILE in your environment wins: no --config is passed.
• If the file has not been pulled yet, the session starts with the global config and the pre-launch check shows a warning ("run nexus pull").

nexus doctor claude shows which Zellij config a workspace uses: project-local, ZELLIJ_CONFIG_FILE or global.

Agent observer

The observer pane shows the agents of the current workspace at a glance: the main agent with its subagents as a tree, background processes, state, current tool, runtime, model and repository or worktree.

It is fed by the nexus-agent-observer hook (part of nexus-core), which writes one nexus.agent-observation.v1 record per hook event to .nexus/claude/observer/events.jsonl. The pane runs:

nexus status --agents --watch

The command is local only (no login, no network), so it also works in a second terminal next to a --plain session.

AgentHUD (experimental)

Under the observer switch you can choose AgentHUD, a third-party observer, instead of the Nexus observer. The pane then runs agenthud and requires lists it; it is never added to devbox.json. nexus doctor claude checks for it and fails when it is missing; --fix only prints the upstream install instruction (npm i -g agenthud) and never runs it.

Sessions named after the project

Rendered layouts set the Zellij session name to the project slug (lowercase, a-z, 0-9 and -, at most 32 characters) and attach to an existing session. A second nexus run in the same project joins the running workspace instead of failing. A custom layout that sets its own session_name keeps it.

Managing presets

Platform admins manage the presets and the system default under Dashboard > System > Settings, tab Workspace Profiles. The same component serves the admin view and My Settings: runtime tabs (Claude Code; OpenCode is in development), preset list, panel switches, preset JSON editor and rendered preview, with the same Validate and Save steps.

Files and CLI

The personal files are checked against their sha256, recorded in the pull manifest and shown by nexus status, nexus diff and nexus reset. A local edit is reported and kept unless you pull with --force; nexus push refuses them.