Project settings

Open Settings → Projects. The project and machine pickers start at All projects and All machines. All projects lists every project with the space it uses, followed by the defaults; select a project to open its settings.

Change the default model, workspace, automatic pull, agent browser access, or actions for projects that inherit those values. Select an individual project to override a default. Reset its row to inherit again. Changing a default preserves explicit project overrides. Workspace preferences in vc.json take precedence over machine defaults when the project has no explicit workspace override.

Select a machine to limit edits to it. All machines writes defaults to connected machines; offline machines keep their previous values. Mixed values are indicated when selected machines or checkouts disagree. Browser access changes apply when an agent session next starts.

Project grouping has a client-wide default across machines, with individual checkout overrides. Shared actions apply to inheriting projects; editing a project’s actions creates an independent list. Reset that list to use shared actions again. Existing project actions are preserved.

Project names, icons, removal, and importing actions from a checkout remain project-specific. When there are several checkouts, the checkout picker selects which actions and grouping to edit.

Account and quota recovery

Select a checkout and open Account and quota recovery to override its environment’s recovery policy. Choose an ordered fallback list of account and model pairs, or restore inheritance to follow the environment again. Individual threads can override the project policy in their account and quota recovery settings. On mobile, project policies are listed in Settings → Account and quota recovery. See switching and recovery for retry choices and limits.

Analyze project directories

Open Storage from the main navigation or Analyze project storage in the command palette. Choose an environment and project, then Scan storage. The result shows dependencies, build outputs and caches, Git data, and other source files, with the largest folders and files below. Scan again refreshes the snapshot. On mobile, use Settings → Project Storage → Project directories.

Use Scan all projects to scan every project in the current environment filter. Only connected environments are included; each project’s result appears as its scan finishes.

Scans measure file sizes on the project’s environment. They do not follow symbolic links or include Git stores outside the selected directory. Nested project directories can overlap, so adding their totals does not give unique disk usage. Large scans may return a labeled partial result. VC’s conversation history and attachments are measured separately. Scanning does not delete files.

Free up storage

Deleting a thread removes its history from VC’s database right away. VC reuses that space for new work, but the database file keeps its size until it is compacted. All projects shows how much each project keeps and how much can be freed. Free up compacts the database to return that space to the disk, which can take a moment on a large history. To clean one project, open it and use Storage to delete its archived threads permanently. Files in your project directories are never touched.

On mobile, open Settings → Project Storage and tap a project.

Project icons

Choose an icon, emoji, or image from the project to make it easier to recognize. The choice applies to selected checkouts in the project group and appears on connected clients. Choose Automatic to let VC detect an icon again.

Keep the default branch current

Enable Automatically pull to keep the default-branch checkout up to date with its configured upstream.

VC only pulls when it can fast-forward and the checkout has no changed files, untracked files, or local commits. It skips checkouts on another branch or without an upstream. If a checkout has local work, resolve it yourself before automatic pulls can resume.

Workspace context

Workspace context gives a new agent session a short, factual picture of the checkout before it starts reading files: the branch and uncommitted files, what other panes changed recently, the project layout, and whether a code index is available. Later turns receive a small delta when other panes changed files since this thread’s last completed turn.

• Workspace context — the master switch. Use On/Off to override the machine default for this project. Changes apply from the next agent session.
• Brief — the checkout summary injected at the first turn of a new session.
• Delta — file changes from other panes in the same checkout, injected before later turns.
• Code graph — registers a codegraph_explore tool with the agent when CodeGraph is installed and the checkout has an index. Install, update, and uninstall CodeGraph here; VC installs it under its own data directory and never edits your agent configuration. Telemetry is off unless you explicitly enable it.
• Agent preview — the exact brief text the next session would receive, with its approximate token size.
• Recent activity — completed turns from other panes in this checkout.

Index actions appear only when CodeGraph is installed and enabled: Re-index rebuilds from scratch, Sync applies pending changes, Stop ends a running job, and Delete removes the index (the checkout returns to “Not indexed”). Very large repositories ask for confirmation before the first index.

A checkout is the project directory, or the thread’s worktree when it has one. Panes in different checkouts never see each other’s file lists.

Work with other people

Open Collaboration from a project’s workspace, Settings → Projects, or the command palette. One person creates a group on a computer that stays running and chooses the base branch and a reachable LAN or tunnel address. Each teammate uses Join group, pastes an invitation, and selects their own checkout of the same Git repository. Everyone keeps their own branch, files and agents on their own computer.

The group shows saved file changes, including commits on a branch that have not been confirmed merged. Select a file to read its diff. Overlapping files identify work that may need coordination; they do not necessarily mean Git will report a merge conflict. An offline member’s last update can be stale. When the host returns, connected machines share their current state again.

Use Pause sharing to stop publishing your changes and resume when ready. Add exclusion patterns for paths you do not want to share. Ignored files and common secret files are excluded by default. The group owner can create or revoke invitations and remove members. Invitations grant access to this group’s shared activity, without access to teammates’ terminals or agent controls. Leaving a group stops sharing; it does not delete your checkout or branch. When creating another invitation, the owner can choose a different reachable LAN or tunnel address for the same group. Direct and tunnel connections can be used at the same time.

To give each teammate their own branch, enter a Teammate branch when creating the invitation. Joining switches the chosen checkout to that branch, creating it from the base branch when it does not exist yet; commit or stash uncommitted changes first. The owner can change or clear a member’s branch later with Branch next to their name. VC does not switch an existing member’s checkout; everyone sees a warning while that member works on a different branch.

Agents receive a short group summary at the start of a turn and can request current file changes and diffs when their provider supports VC tools. On mobile, open Collaboration to view the group through your connected environment. Commit, push and merge through your usual Git workflow.

Linked workspaces

Link a project to another project on the same machine when its agents should know what the other project is doing — for example a backend that a frontend depends on. Drag a workspace onto another project’s workspace in the sidebar, or open the project, choose the checkout, and use Linked workspaces to add or remove links.

A link is one-directional: threads in this project can read the linked project’s memory entries and see its recent activity (thread titles, changed-file counts, and a short turn summary), but the linked project does not see this project unless you add a link there too. Agents in this project gain a read-only memory_query tool and can read the linked project’s checkpoints through workspace_changes; they cannot write its memory. Links are local to this machine — linking a project on one machine does not link its counterparts elsewhere.

Enable Workspace context to give agents a brief and subsequent activity updates automatically.

A linked project that was deleted stays listed as missing until you remove it. Linked activity under Workspace context previews what agents in this project will see.

To see every link on a machine at once, open Settings → Projects → All projects and look at Linked workspaces, or use the link icon in the sidebar. Both list each link with a switch that pauses sharing without removing the link — paused links stop granting memory and activity access until switched back on.