02 / Daily operations

Projects & worktrees

Chart the folders you work in. Keep their agents close to home.

Roots and single folders

A sector root is a folder containing projects. Open V and press n to add one. Each addition keeps your existing roots. Discovery walks beneath the roots, stops inside repositories, and skips hidden directories, symlink directories, node_modules, target and vendor.

A manual planet is one folder you add with n from the galaxy or Home. It can be outside your roots and does not need Git. Adding a planet does not launch an agent.

With no saved root, Empire uses /home/code or ~/code when one exists. On Home, uppercase R rescans all roots; lowercase r opens the folder manager. Discovery reads directory entries. It does not clone, pull or edit repositories.

Find your way Home

Press H from the galaxy. Home puts projects needing your input or review first, then groups other projects by their parent folder. The selected project's full path appears in the footer.

Enter opens a project, e launches an agent there, and r manages folders. In the galaxy, use z to fit the map and f to focus the selection. o toggles the outliner.

Worktree stations

A Git worktree appears as a small ▣ space station around its project planet. It has a core, a truss and two solar wings, with amber lights while an agent is aboard. It is separate from the ring-shaped GitHub station.

Empire checks each repository's worktree registry about every eight seconds while the galaxy is open. Worktrees made by your agent can appear even in hidden folders or outside sector roots. Missing worktrees are skipped; stations you explicitly hide stay hidden.

Create and merge worktrees with Git or your agent's normal tools. Empire discovers existing worktrees; it does not manage their creation or merging for you.

Moving an agent's work

Ask the agent to create the worktree and execute its work there. For Codex, Empire follows working directories in completed-command session records. Claude and Grok hooks can also report a changed native working directory.

The ship keeps its identity and conversation. Unfinished missions assigned to it move with it; unassigned project tasks stay on the original planet. Empire only follows another checkout of the same repository. A shell-internal cd or a command using only git -C may not report the change; use the worktree as the command's working directory.

Remove from the map

Select a project on Home or the galaxy and press x or Delete. In the folder manager, the same controls remove a selected root or manual folder.

This hides the project from the map. It does not delete its files or stop its sessions. Worlds with sessions remain visible until those sessions are dismissed. Adding the folder again restores it. Removing a root keeps projects covered by another root or added individually.

Project resources

Open a project's resources to inspect instruction files, skills, commands, subagents, hooks and MCP configuration. Enter or e opens a file in your editor: $VISUAL, $EDITOR, or an available terminal editor.

On an empty resource plot, Enter or n creates a first draft and opens it. Existing files are not overwritten. Uppercase B prepares a task for an agent to build or renovate that resource. Review the brief before sending. Ctrl+R rereads the files.