- Features
- Worktrees & hooks
Every session gets its own checkout, ready to run.
Plexus creates a git worktree for each session, copies in the env files git leaves out, gives the session its own ports and runs your setup scripts. You write each script once, at the level where it belongs.
One worktree per session
Starting a session creates a git worktree for it, by default at <project>/worktrees/<session-name>, on a new plexus/<name> branch off the base you picked or on an existing branch. Plexus adds the folder to .gitignore so worktrees never show up as untracked changes. Removing a session removes the folder and git's own record of it. Plexus never deletes a branch it did not create without asking you first.
Read it in the docsLive demo · simulated sessionsProject Git tab
The files git leaves out
A new worktree contains only tracked files, so .env and .env.local are missing and a dev server that needs them would fail. Plexus copies a list of files and folders into every new worktree, .env and .env.local by default, whether git tracks them or not. Paths must stay inside the repository: absolute paths and .. are refused, and symlinks are skipped.
Read it in the docsLive demo · simulated sessionsSessions, hooks tab
Ten ports for each session
Two sessions of one repository both want port 3000. Plexus reserves a block of 10 free localhost ports for each session, from 20000–31999 by default, and exposes them as PLEXUS_PORT, PLEXUS_PORT_1 to PLEXUS_PORT_9 and PORT. The agent, the session's terminal and every hook get them. A session keeps its block when it resumes. Open localhost in the session's tab strip opens your browser on that port.
Read it in the docsLive demo · simulated sessionsSessions, agent tab
Create, Run, Teardown
A hook is a shell script attached to one of three events. Create runs when the worktree is made: install dependencies, write local config. Run fires every time the agent starts or resumes: start a dev server or a watcher. Teardown runs when a session is removed: stop containers, clean up. The Hook output tab keeps each hook's output and exit status, and a hook that runs too long is stopped after the timeout, 600 seconds by default.
Read it in the docsLive demo · simulated sessionsSettings, Worktrees & hooks
Three levels, one resolved plan
Hooks are defined globally, per workspace or per project, and resolved from global down to project. Each workspace or project picks how its hooks join the ones it inherits: Override, Before, After or Parallel. The Resolved plan preview shows exactly what will run and in which order, with a badge saying where each hook came from, so you can check inheritance before you start a session.
Read it in the docsLive demo · simulated sessionsSettings, Worktrees & hooks
Hooks that ship with the repository
Commit hooks to .plexus/hooks.json and everyone who adds the repository gets them. They run alongside the hooks you set up in Plexus, and a setting decides which run first. Repository hooks run on your machine with your permissions, so Run scripts committed to the repository lets you switch them off for repositories you do not trust. Plexus removes Anthropic credentials from every hook's environment.
Read it in the docsLive demo · simulated sessionsSettings, Worktrees & hooks
Read more
- Worktrees & env files: where worktrees live, copying files and dev-server ports
- Lifecycle hooks: events, levels, combine modes and the hook environment
- Sessions & worktrees: new and existing branches, root-tree sessions
Questions,
Can I start a session without a worktree?
Yes. Start session on root tree runs the session directly in the project's main checkout. It is meant for quick edits. Sessions on the root tree share one working directory, so use a normal session when you want isolation.
My dev server ignores PORT. What do I do?
Next.js, Nuxt, Rails and Express read PORT themselves. Vite, Astro and Angular do not, so pass the port on the command, for example pnpm dev --port $PLEXUS_PORT in a Run hook. On Windows, hooks run through cmd.exe, so write %PLEXUS_PORT% there.
What happens if a Create hook fails?
With Stop if a setup step fails switched on (the default), a Create hook that exits with an error stops the launch, so you never get a half-prepared worktree. Run and Teardown hooks never stop the lifecycle. A hook that times out is reported but does not stop the launch.
Do repository hooks run automatically?
Yes, while Run scripts committed to the repository is on, which is the default. Keep it on only for repositories you trust, or switch it off per project.
Run your agents
Plexus is free to download for macOS, Windows and Linux. It runs the Claude Code you already have, with your existing login.