Apps And Worktrees

Apps and worktrees are the core model in Divine. An app is the active WordPress theme on a site. A worktree is a git-backed copy of that theme directory, made for one task, that you can edit, check, preview, review, and deploy without touching the theme your visitors see. Every Divine surface, including canvas, previews, code, review, and deploy, operates on one of these two targets.

The rule of thumb is one worktree per task. Whether that task is a single agent run, one new template, or one block redesign, keeping it in a dedicated worktree keeps unfinished work away from the live theme and cleanly separated from whatever else is in flight. Because each worktree is its own theme directory, several people or agents can work on the same app at the same time without colliding.

What an app is

An app is the installed, active theme registered with Divine as a workspace. On a single-site install, the app is the one active WordPress theme; on a multisite install, Divine runs from network admin and an app is one network site together with its active theme. Registering a theme records its stylesheet slug, label, domain, and workspace metadata in Divine’s theme registry, but the theme itself stays an ordinary WordPress theme. If it is active, it keeps serving the live site while Divine adds workspace behavior around it.

The app is the deploy destination, not the editing surface. App file browsing is read-only for general edits, because changes that should reach the live theme are expected to travel through a worktree and its review step. The blog_id is part of the app identity on multisite, so a worktree, a preview, a token, and a deploy all carry the site they belong to.

What a worktree is

A worktree is a full copy of an app theme placed alongside it under wp-content/themes/<worktree-id>. Divine generates a slug shaped like <app-slug>--worktree--<name>-<suffix>, copies the source files together with the .git directory, refreshes the Divine-managed theme files, and registers the copy as a worktree record. Because the copy carries its own repository, Divine can inspect changed files, insertions, deletions, conflicts, and commit history without needing a git binary on the host.

A worktree is a real directory, so anything with filesystem access can write to it: the Divine code editor, a coding agent, or your own tools. The REST file routes can additionally read a file, write a file, delete a file, and return a unified diff of a changed file against the worktree’s base state, so the admin app and an agent both work through the same surface.

Worktree records

The worktree ID is the handle for everything that follows. The REST API and the admin app expose the same core fields for each worktree, and each cell stands on its own.

Field	Meaning
id	The worktree theme slug, used as the stylesheet for the copy.
app	The owning app slug the worktree was created from.
blog_id	The network site the worktree belongs to, or none on single-site.
name	The human label given at creation.
status	Always active; a worktree exists only while its directory and record exist.
url	The clean site URL the in-app preview browser opens.
workspace_path	The real theme directory on disk.
git_stats, git_overview	Changed, staged, untracked, and conflicted file counts.
changes	Per-file status, insertions, deletions, and paths.
worktree_count	How many worktrees currently exist for the owning app.

There is no separate database history for a worktree. The repository copied into the worktree directory is the record of what changed, so lineage and history are git-tracked rather than stored in a Divine table.

Git-tracked lineage

A worktree’s history lives in its own .git directory, not in a Divine database. When Divine creates a worktree, it copies the source theme’s repository, so the new worktree starts from exactly the commit history of whatever it was cloned from. From that point the worktree is an independent line of work: edits, diffs, and any commits stay inside that copy until the work is deployed.

This is why Divine can show changed files, insertions, deletions, and conflicts for a worktree without keeping its own change log. Inspection reads the worktree’s repository directly. It also means lineage follows the clone source: a worktree cloned from another worktree inherits that worktree’s state at copy time, so you can branch a refinement off an in-progress task rather than always starting from the app.

Creating a worktree

Creation is where Divine builds the isolated copy and enforces its guardrails before any files are written. You create a worktree from the admin app or with POST /wp-json/divine/v1/apps/<app>/worktrees. The call requires a name, and it accepts an optional clone_from to copy an existing worktree instead of the app’s main theme.

Before copying anything, Divine confirms the caller can manage Divine, resolves the source as either the registered app theme or one of its worktrees, and asserts that the source directory is a real git workspace. If the .git directory is missing, creation fails with a validation error rather than producing a copy with no history. Once the checks pass, Divine copies the theme into a unique slug, refreshes the managed theme files, commits a managed-files baseline so generated files are tracked, and stores the worktree record. If the record cannot be written, Divine deletes the half-built copy so a failed creation does not leave an orphaned directory behind.

The supported clone sources are described below.

clone_from value	Source copied
Omitted or main	The app’s active theme directory.
A worktree ID	That worktree’s current workspace directory.

Lifecycle

Work in a worktree follows a deliberate path, and nothing along it is implicit. A change does not reach the app theme simply because it exists in a worktree; deploy and destroy are explicit, separate steps.

1. Create the worktree from main or from another worktree.
2. Edit normal theme files inside it.
3. Preview the result in canvas and the signed browser preview.
4. Review the changed files and resolve any conflicts.
5. Deploy the accepted files into the app theme, or destroy the worktree.

Deploy is the step that mirrors the worktree’s files into the app theme. Divine writes any resolved files into the worktree, inspects its git state, and refuses to proceed if conflicted files remain. It then mirrors the worktree contents into the app theme directory and immediately destroys the worktree. Deploy promotes files only; on multisite it targets the selected site’s active theme, and it never copies database state. See Deploy for the full file-level behavior.

Destroy is the cleanup path for a worktree you do not want to keep, and it is also the final step of a successful deploy. It deletes the copied theme directory and removes the registry record. Discarded work never reaches the app theme, and a destroyed worktree’s preview session and share links stop resolving because the record that backed them no longer exists.

Working in parallel

Because each worktree is a separate theme directory with its own repository, Divine supports many worktrees at once for the same app, including several agents working simultaneously. The practical thing to manage in that situation is clarity, not collisions: give each worktree a descriptive name so you can tell at a glance which task each one represents when you come to review and deploy.

Keep worktrees task-shaped, and deploy or destroy them when they are done. Long-lived copies make review queues harder to reason about and drift further from the app theme with every change that lands on the app in the meantime.