Projects, chats, and worktrees

Every session runs in a folder on the daemon’s machine. There are three kinds:

• A task runs in a project: a folder you picked.
• A chat runs in a private, empty folder that Weaver creates for it.
• A task can also run in its own Git worktree, so several sessions can change the same repository without touching each other’s files.

Projects

A project is a folder that a session works in. It can be a Git repository or a plain folder.

You add projects through the project picker when you start a task (⌘N). The picker offers three ways in:

• Pick from the list. The list holds every folder you have added plus every folder a session has used, newest first. Folders that no longer exist are left out.
• Use an existing folder. A folder browser on the daemon’s machine. It starts at your home directory and hides dot-folders.
• Start from scratch. Creates a new, empty folder with the name you type in ~/Documents on the daemon’s machine. Names are cut to 64 characters, and /, \ and : become -. The name must not already exist there.

The list is stored in projects.json in the Weaver data directory (~/.pix on macOS, ~/.local/share/pix on Linux). The session logs are the source of truth. The list only feeds the picker.

If a linked worktree of a repository and its main checkout are both in the list, the picker shows one row for the repository. Sessions from the worktree are listed under the main checkout.

Choosing the project for new tasks

Settings → General → New tasks → Project controls what the picker preselects. Every new task still shows the picker.

• Always ask: nothing is preselected.
• Last used (the default): the last project you used.
• Fixed: a project you choose.

This setting is stored on the device, not on the daemon.

Per-project defaults

Settings → Projects & New Tasks sets defaults for future sessions in one project. Pick the project, then set:

• the suggested agent for that project, or inherit the profile’s suggestion, and
• each agent’s starting configuration (model and its options) for sessions in that project.

Existing sessions keep their settings.

Projects in the sidebar

The sessions panel has three views, switched from its header:

• Flat list: every session, newest first.
• Group by project: sessions grouped under their project. A project’s Folder options button has New chat… (start a session in this project with an agent you pick), Reveal in Finder (when the daemon runs on a Mac), and Collapse all / Expand all.
• Open project session catalog (when the daemon supports it): open projects as tabs and page through each project’s full history, including sessions from its worktrees.

Chats

A chat is a session without a project. Use it for questions that do not need your code.

Start one with Chat in the sidebar, or press ⇧⌘N, and pick an agent in Chat with….

Each chat gets its own empty folder, readable only by you, at chats/<session id> in the Weaver data directory. That folder is the agent’s working directory. It never appears in the project picker. Chats are listed together under Chat at the bottom of the grouped view. Search for chat or scratch to find them.

A chat inherits only the agent’s own defaults, not any project’s defaults. Pressing ⌥⌘N in a chat starts another chat.

Worktrees

A worktree is a second checkout of the same Git repository, on its own branch, in its own folder. When a session runs in a worktree, its edits do not touch your main checkout or other sessions.

Turn it on

Go to Settings → General → New tasks and set Always use a worktree to on.

The setting applies to sessions you create after you change it. Each session records the value when it is created, so changing it later never moves an existing session.

Chats never use worktrees.

What happens

1. You start a task in a project as usual. The session is listed under the project’s main checkout.
2. When you send the first message, Weaver creates the worktree. Nothing is created before that.
3. The worktree is based on the commit currently checked out in the main checkout (HEAD). Uncommitted changes in the main checkout are not copied.
4. Weaver names the branch and folder from the first message: up to six words, with filler words such as “please” and “the” dropped, at most 44 characters. The branch adds the first 12 characters of the session ID, without dashes. A first message of “Fix the login redirect bug” gives a branch like pix/fix-login-redirect-bug-1a2b3c4d5e6f.
5. The worktree folder is in the Weaver data directory, at worktrees/<project id>/<name>-<session id>.
6. If your project is a subfolder of the repository, the agent works in the same subfolder inside the worktree.

Requirements

The first send fails with an error if:

• the project is not inside a Git repository,
• the repository has no commits yet,
• you opened the project from a linked worktree instead of the main checkout,
• the branch name already exists at a different commit, or
• the project’s subfolder does not exist at the base commit.

Turn the setting off, or fix the repository, and start a new session.

Find and inspect a worktree session

• In the session list, a worktree session shows the worktree’s name next to the project path. Hover for the branch. If the worktree folder is gone, the row says the worktree is unavailable.
• Search matches the worktree’s name, branch, and path.
• The session’s menu has Copy worktree path and, when the daemon runs on a Mac, Reveal worktree in Finder.
• The inspector has a Workspace root menu with Local checkout and Worktree. It changes which checkout Files, Changes, Local Changes, and Terminal show. Switching only changes what you are looking at. The agent keeps running in the worktree.

Weaver also detects worktrees it did not create. If a session’s project is a linked worktree, or an agent creates a worktree and edits files in it, the session is listed under the main checkout with the worktree’s name.

Merge and clean up

The worktree branch is an ordinary local branch in your repository. Merge it, rebase it, or open a pull request from it with your normal Git tools, or ask the agent to do it.

Weaver does not delete worktrees or their branches. When you are done with one, remove it yourself:

git worktree remove <path>
git branch -d pix/<name>

Use Copy worktree path to get the path.