▄▄▄▄▄▄▄▄ ▄▄ ▄▄
█▀▀▀▀▀██▀ ██ ██ █▄
▄█▀ ██ ██ ▀▀ ▄▄ ▄ ▄██▄
▄█▀ ▄█▀█▄ ██ ██ ██ ▄████ ▄█▀█▄ ████▄ ██
▄█▀ ▄ ██▄█▀ ██ ██ ██ ██ ██ ██▄█▀ ██ ██ ██
████████▀▄▀█▄▄▄▄██▄██▄██▄▀████▄▀█▄▄▄▄██ ▀█▄██
██
▀▀▀
Zelligent runs AI coding agents in isolated git worktrees, each in its own Zellij tab.
You give it a branch name and an agent command. It creates a worktree, opens a new tab with a persistent sidebar on the left and an agent plus lazygit on the right. When you're done, it cleans up the worktree.
Use the CLI to spawn worktrees, or use the always-visible sidebar inside zelligent-managed tabs to switch, create, and remove worktrees.
Install with Homebrew (pulls in Zellij and lazygit automatically):
brew install pcomans/zelligent/zelligentRun the setup wizard:
zelligent doctorThis installs the Zellij plugin, creates ~/.zelligent/layout.kdl if it is missing, configures plugin permissions and session serialization, and syncs the bundled Claude skill to ~/.claude/skills/zelligent-spawn-claude/SKILL.md (Homebrew installs use a symlink to keep it updated across upgrades). It also sets up clipboard support on macOS. Safe to run more than once.
Start a session:
cd my-project
zelligentThis opens a Zellij session named after your repo. If the session already exists, it reattaches to it.
Spawn an agent in a new worktree:
zelligent spawn feature/my-feature claudeThis creates a git worktree branched from the branch you're currently on (so spawning from inside an existing worktree continues on top of that work in progress), opens a new Zellij tab, and runs claude (Claude Code) in it. The tab is split 70/30 between the agent and lazygit.
On first launch, Zellij will ask you to grant the plugin permissions. Select y — the plugin needs these to manage worktrees and tabs.
Zelligent has two parts: a shell script that manages git worktrees and Zellij sessions, and a Rust plugin (compiled to WASM) that provides the embedded sidebar UI inside Zellij.
The zelligent command handles worktree creation, layout generation, and session management.
When you run zelligent spawn feature/auth claude:
- It creates a git worktree at
~/.zelligent/worktrees/<repo>/<branch>/, branched from your current branch (ororigin/HEAD/mainif HEAD is detached) - It generates a Zellij layout file (KDL format) with an embedded left sidebar plus the main tab body
- If you're inside Zellij, it opens a new tab. If you're outside, it creates or attaches to the repo's session
If the branch already exists, it reuses the existing worktree instead of creating a new one.
The plugin is embedded as a persistent left sidebar in every zelligent-managed tab. It lists your active worktrees and lets you create, open, or remove them without leaving the terminal.
| Key | Action |
|---|---|
j/k or arrows |
Navigate the list |
Enter |
Open the selected worktree |
n |
Pick from existing git branches |
i |
Type a new branch name |
d then y |
Remove the selected worktree |
r |
Refresh |
When you remove a worktree through the plugin, it also closes the corresponding tab.
zelligent # launch/attach session for current repo
zelligent spawn <branch-name> [agent-cmd] # create worktree and open agent tab
zelligent remove <branch-name> # remove a worktree
zelligent init # create .zelligent/ hook stubs
zelligent doctor # check and fix setup
zelligent spawn adapts to context:
| Context | Result |
|---|---|
| Inside a Zellij session | Opens a new tab in the current session |
| Outside Zellij, session exists | Attaches to the session, opens a new tab |
| Outside Zellij, no session | Creates a new session |
zelligent remove refuses to delete worktrees with uncommitted changes. The local branch is kept.
Run zelligent init to create hook stubs, or create them manually.
.zelligent/setup.sh runs inside the new tab when a worktree is first created. Use it to copy config files, install dependencies, or anything else the agent needs before it starts.
#!/bin/bash
REPO_ROOT=$1
WORKTREE_PATH=$2
cp "$REPO_ROOT/.env" "$WORKTREE_PATH/"
cd "$WORKTREE_PATH" && npm installIf the setup script fails, the agent command won't start and the pane stays open so you can read the error. The script only runs on first creation — reopening an existing worktree skips it.
.zelligent/teardown.sh runs when a worktree is removed:
#!/bin/bash
REPO_ROOT=$1
WORKTREE_PATH=$2
rm -f "$WORKTREE_PATH/.env"Create .zelligent/layout.kdl to override the default tab layout. This file is a fragment, not a full layout { ... } document. Zelligent owns the outer wrappers and renders these placeholders:
{{zelligent_sidebar}}required exactly once{{zelligent_children}}required exactly once{{cwd}}optional{{agent_cmd}}optional
Example:
pane split_direction="Vertical" {
pane name="zelligent" size=36 {
{{zelligent_sidebar}}
}
pane {
pane command="{{agent_cmd}}" cwd="{{cwd}}" size="70%"
pane command="lazygit" cwd="{{cwd}}" size="30%"
}
}
pane size=1 borderless=true {
plugin location="zellij:status-bar"
}Custom layouts bypass the automatic setup.sh preamble. If you need setup to run before the agent, wrap it in your command, e.g. args "-c" "bash .zelligent/setup.sh /repo /worktree && exec {{agent_cmd}}".
When using Claude Code (or another agent with hook support), zelligent tracks agent status and shows it in the plugin UI:
| Indicator | Meaning |
|---|---|
● (green) |
Agent is working |
● (yellow) |
Agent needs input (permission prompt, etc.) |
✓ (green) |
Agent finished |
On macOS, you also get desktop notifications with a sound when an agent needs input or finishes. This uses osascript and is currently macOS-only.
zelligent doctor sets up the required hooks automatically when Claude Code is installed.
These are Zellij's default keybindings:
| Action | Keybinding |
|---|---|
| Next tab | Ctrl-t n |
| Previous tab | Ctrl-t p |
| Rename tab | Ctrl-t r |
| Close tab | Ctrl-t x |
| Switch panes | Ctrl-p + arrow keys |
Zellij automatically saves your session layout periodically and restores it when you reattach. By default it snapshots every 60 seconds, which means tabs you closed in the last minute can reappear after a restart.
zelligent doctor sets serialization_interval 5 in your Zellij config so snapshots are taken every 5 seconds. This keeps the saved state close to what you actually see, so closed tabs stay closed after resurrection.
git clone https://github.com/pcomans/zelligent.git
cd zelligent
PATH="$HOME/.rustup/toolchains/stable-$(rustc -vV | grep host | cut -d' ' -f2)/bin:$PATH" bash dev-install.shRequires Rust via rustup with the wasm32-wasip1 target (rustup target add wasm32-wasip1).