Codebases

Track Git repositories and checkouts across every enrolled agent.

The Codebases page at /dashboard/codebases is the inventory of every Git repository registered on every enrolled machine, with live sync and availability status for each one.

Codebases and repositories

Two concepts sit behind this page, and the distinction matters:

Codebase

One checkout on one agent — a folder on a specific Mac. Branches and stashes are managed here.

Repository

The logical repository behind every checkout that shares an origin. Skill groups, build configurations, and Auto Retry live here and apply everywhere.

Use Agents to see what each machine hosts, Repositories to see where a repository is checked out, or Branches to clean up local branches across all agents. The iOS app offers the same three views.

Clean up local branches

The Branches tab lists local branches from every registered checkout. Each row identifies the repository, agent, folder, last local commit, age, and last successful scan. The same branch name on two agents represents two separate local branches.

On the web, the Repository column shows the folder relative to that agent’s Base repository directory. Hover over the folder to see its full path. Folders outside the base directory, or on agents without a configured base, show their full paths. Long column text wraps; narrower screens let you scroll the table horizontally.

Both clients start with all agents, all repositories, and no age restriction, sorted oldest first with unknown ages last. The web shows 50 branches per page; iOS uses a native scrolling list. Configure the codebase’s default branch before cleanup if it is unknown.

1. Filter by Agent and Repository. A repository filter includes its checkouts across agents.
2. Choose Older than: any age, 7, 30, or 90 days, or a custom positive number of days. Age means time since the commit at the local branch tip, not when the branch was created. Unknown dates are excluded when an age filter applies.
3. Check individual branches or choose Select all matching eligible branches. On the web, this includes matching branches across all pages. Changing filters or leaving the tab clears your selection.
4. Choose Delete selected and review the branch names, agents, and checkout folders before confirming.

Normal deletion uses Git’s merged-branch checks. To remove unmerged branches, enable Force delete unmerged branches and accept the separate confirmation before deleting.

Force deletion can remove local commits that have not been merged or pushed. Both deletion modes protect the current branch, the default branch, and every branch checked out in a worktree. Cleanup never deletes a remote branch or a remote-tracking ref.

Offline agents retain their last successful inventory, with deletion disabled until they reconnect. Failed scans keep the previous inventory and show a scan failure. Older agents can show recorded local branch names with unknown metadata; update the agent and refresh before cleanup becomes available.

Refresh inventory queues a local scan without fetching origin. Background reconciliation also refreshes the inventory. The control plane stores branch names, tip hashes, commit subjects and dates, worktree paths, and the scan timestamp for each registered codebase. Removing a codebase removes this cached inventory with its registration.

Cleanup runs one job per checkout and reports each branch as deleted, skipped, or failed. A changed branch tip or newly active worktree blocks deletion even after confirmation. Other branches continue when one fails. After a timeout or connection loss, refresh the inventory to confirm what remains before retrying.

The iOS app uses native selection buttons and the same filters, review, force confirmation, and per-branch results.

Status

Each codebase carries two independent statuses.

Sync state

State	Meaning
In sync	Local branch matches its upstream
Ahead	Local commits not yet pushed
Behind	Upstream commits not yet pulled
Diverged	Both sides have commits the other lacks
No upstream	The branch tracks nothing
Detached	HEAD is not on a branch
Unknown	Not yet determined

Availability

State	Meaning
Available	The folder is present and is the expected repository
Folder missing	The registered path no longer exists on the agent
Not a Git repository	The folder exists but has no Git metadata
Origin changed	The remote origin no longer matches what was registered
Unavailable	The agent reported an error inspecting it

Rows also show the folder, origin, current branch, upstream, ahead and behind counts, last checked, and last fetched.

Adding a codebase

1. Pick an online agent

   Only connected agents can be browsed. Offline agents cannot report what is on disk.

2. Browse to the folder

   Start from the agent’s home folder and navigate. Show hidden folders reveals dotfiles. Long directories are capped at the first 1,000 entries.

3. Inspect and confirm

   Add this folder inspects the repository and reports its origin and current branch, including a detached HEAD. If the origin already has a registered checkout, the page tells you the shared repository name it will join.

4. Name it and save

   Set the Repository name and an optional description, then Confirm codebase.

Bulk actions

• Refresh all re-inspects registered folders and reports Git status without contacting remotes.
• Fetch all runs git fetch origin for eligible codebases.

Both skip codebases whose agent is offline, unsupported, or whose folder is unavailable, and report how many were skipped.

Settings

Cadence defaults that apply to every updated agent:

Setting	Notes
Agent refresh interval	How long each agent waits after a scan completes before scanning again. Git remotes are not contacted.
Automatic fetch interval	How often each agent fetches origin.
Default Jira branch regex	Extracts a ticket key from a branch name. The first capture group is used when present, otherwise the whole match.

A single agent can override the refresh and fetch intervals on its own detail page, and a repository can override the Jira branch regex on its repository page.

Removing a codebase

Remove deletes the registration only. The folder and all of its files stay untouched on the agent — the control plane simply stops tracking it.

Notes

• Read-only codebase data is also available over REST at /api/codebases and through MCP at /api/mcp.
• A codebase with a Git operation, Git-blocking command, or Git-blocking workflow terminal step in flight shows a specific in-progress message and blocks conflicting actions until it finishes.

Related pages

Codebase details

Branches and stashes for one checkout.

Worktrees

Linked worktrees created from these repositories.