Spaces and worktrees

A Space is a project with an Emacs tab of its own. A git worktree is a Space of its own too, shown under its repository.

How a Space works

The sidebar is on the left, a tab for each project is at the top, and a transcript sits to the right of the source. They are ordinary windows: split, move and close them as you like. Leaving a Space and coming back restores its windows.

A session you start or pick in the sidebar takes the window of the session used longest ago. That session keeps running without a window, and the sidebar or C-c c V brings it back.

Going to a Space with nothing running starts a session there, and killing its last session closes the Space. Type /resume in the new session to carry on an earlier conversation. With ecc-space-always-session off, a Space opens on the source alone and stays until you kill the project’s last buffer.

Key	Command	Action
C-c c j	ecc-space-goto	Go to a Space by name, including a project that only has recordings
C-c c z	ecc-space-zoom	Fill the tab with this window; again to restore
C-c c V	ecc-space-cycle-layout	Lay the Space out again in its layout. Pressed again, move to the next layout
C-c c ? then X	ecc-space-close	Close this Space and stop everything in it, its worktrees included, then offer to remove those worktrees
—	ecc-space-jump	Go to the Nth Space, as numbered in the sidebar

Layouts

C-c c V rebuilds the tab in the layout it last had, and pressed again right away it moves to the next one. With repeat-mode on, C-c c V V V does the same. C-u C-c c V goes back to the first. Each tab keeps its own layout.

Layout	Windows
source + session	The source, and one session to its right. A new tab opens in this one
two sessions	Two sessions side by side, without the source
source + two sessions	The source and two sessions, a third of the width each
two sessions over the source	Two sessions side by side above, the source below
source + two stacked	The source, and two sessions one above the other to its right
2x2 grid	Four sessions. With three, the source takes the fourth place

The first place goes to the session in the selected window, the others to the sessions used most recently. ecc skips a layout when the Space has too few sessions for it or the frame is too small. The sidebar keeps its width, and sessions without a place keep running.

tab-bar-show decides whether the tab bar is drawn; ecc does not turn tab-bar-mode on itself. With (setq tab-bar-show nil) the Spaces work the same, and the sidebar lists them.

The sidebar

C-c c b (ecc-sidebar-focus) opens the sidebar and moves point into it; again moves point back.

The top half lists the Spaces with their state, their number and their name. A repository shows its branch and how far it is from its upstream, with its worktrees below it. The bottom half lists the sessions, marked as in the tab line.

Key	Action
RET	Go to the Space or session on this line
n, p	Next, previous row
TAB	Fold or unfold a repository’s worktrees
1–9	Go to the Space with that number
c	Start a session in this Space
W	Create a worktree from this Space and start a session there
r	Resume this session (C-u r: fork it), or go to it if it is running
R	Rename this session
k	Stop this session
K	Remove this worktree’s directory
X	Close this Space
a, d	Allow or deny what this session waits on (details)
g	Refresh git status and redraw
q	Hide the sidebar

ecc-sidebar-width sets the width (28 columns). ecc-sidebar-sessions-sort orders the sessions: spaces (the default) under their Space, priority with those waiting for you first.

Worktrees

A git worktree is a second working tree of a repository on a branch of its own, so two sessions can work on one project without seeing each other’s edits.

Key	Command	Action
C-c c ? then W c	ecc-start-worktree	Check out a branch beside the repository and start a session there
C-c c ? then W o	ecc-start-in-worktree	Start a session in an existing worktree
C-c c ? then W k	ecc-remove-worktree	Stop the worktree’s sessions and remove it

ecc-start-worktree offers the existing branches. An existing branch is checked out as it is, and a new one is created from HEAD. If another worktree already has the branch, ecc offers to start the session there.

Worktrees go in ecc-worktree-directory, .claude/worktrees by default. A relative path is under the repository (<repo>/.claude/worktrees/feat-x); an absolute one is shared by every repository (<directory>/<repository>/feat-x).

When the last session in a worktree ends, ecc offers to remove the worktree. No branch is deleted: removing a worktree removes its directory. If the worktree has uncommitted changes or untracked files, ecc names it and asks again before forcing the removal.

Handing work to a session in a worktree

With the Emacs MCP server on (ecc-mcp-enabled), asking a session to do something in a worktree gives the model start_worktree_session. It names a branch and writes a brief. Emacs makes the worktree from HEAD, opens it as a Space, and starts a session there with the brief, adding the files the conversation touched, its plans, its recording and the uncommitted changes. Commit that work first, or say in the brief that it is uncommitted.

If the model tries to make a worktree by itself, Emacs denies the request and points it to the tool. A draft that mentions a worktree goes out with one line reminding the model of the tool, shown folded under your prompt as “1 line Emacs added”. A branch already checked out in another worktree is refused, so two sessions never share one. From Lisp the command is ecc-worktree-delegate.

Without the MCP server, the CLI runs git worktree add itself and carries on in the same conversation.

A day in a Space follows a piece of work through this.

Removing finished worktrees

With the MCP server on, you can ask a session to remove the finished worktrees. The model first calls list_worktrees to see each worktree’s changes, branch, sessions and Space. It then passes the paths you asked for to remove_worktree, which removes a worktree only when all of these hold:

• It has no uncommitted changes and no untracked files.
• No buffer visiting it has unsaved changes, and no prompt of its sessions holds an unsent draft.
• Something was committed on its branch and went into the remote’s develop, main or master, or its pull request into one of them was merged (checked with gh).
• None of its sessions is busy, and no other session has moved into it.

ecc stops the idle sessions and closes the Space. Buffers visiting its files stay open. It leaves every other worktree in place, and the model tells you why. ecc deletes no branch.

Caution

Removing a worktree also deletes the files git ignores in it, such as compiled .elc files, .claude/settings.local.json and node_modules.

remove_worktree runs without asking while ecc-worktree-auto-allow-removal is on, which it is by default. A claude started outside ecc with the Emacs MCP server needs mcp__emacs__remove_worktree in its permission allow list.