Sculptured docs

Git workflows

Review what agents changed, commit it deliberately, and merge each agent's own copy when they work in parallel.

Agents edit files in the project folder on your computer. Sculptured never commits or pushes on its own. The Git page lets you see what changed and commit it yourself, without leaving Sculptured. It also merges each agent's own copy when agents work in parallel.

Open the Git page

With a project open, press Git changes in the workspace header. The page opens on that project's folder. Back to board returns to the Design board.

The project needs a folder, inside your home folder, on the computer that runs it. Otherwise the page says "Choose a project folder first" or "Project folder must be inside your home folder".

Review before committing

  1. Initialize Git if needed
    If the folder is not a repository yet, the page says "No repository in this project folder". Press Initialize repository.
  2. Read the changes
    Each changed file shows its status code and path. Press Diff for unstaged changes, or Staged diff for what is staged. New files show no diff until you stage them.
  3. Stage
    Tick files and press Stage selected, or Unstage selected to take them back out. Up to 100 files at a time.
  4. Commit
    Under Commit staged changes, write a commit message and press Commit staged changes.
  5. Branch, if you want
    Under Create a branch, enter a name. Git creates it and switches to it.

The page shows the current branch and its latest commit, or "No commits yet". Index means staged changes, and worktree means unstaged changes.

Safe by design

BehaviorWhy
Status refreshes on request. Press Refresh status for the latest.Agents and other Git tools can change files at any time.
A changed repository is refused. If the repository changed since you looked, the action is refused with "Repository changed; review the new status".You only commit what you reviewed.
One Git action at a time. A second gets "Another Git operation is running".Two actions never interleave.
Hooks and signing are off for commits made here.Use your terminal if your project needs hooks or signed commits.
Nothing is pushed.Fetch, pull, push and merges with remotes stay in your terminal.

Agents' own copies

When agents run at the same time in one folder, they can overwrite each other's files. To avoid that, give each agent its own copy:

  1. On the Design board, open Project folder and tick Each agent works in its own git copy.
  2. The project folder must be a git repository. Commit first: each copy starts from the last commit.
  3. The setting applies when agents next start.

Each Claude Code or Codex agent then works in its own copy, a git worktree, on its own branch, sculptured/<team>/…. Copies live in ~/.sculptured/copies on the computer unless you chose another copies folder. Agents see each other's work only after you merge it.

Copies that take no extra space. When the copies folder is on the same drive as the project and that drive can clone files (APFS on a Mac, btrfs or XFS on Linux, a Dev Drive on Windows), a new copy shares the project's disk: only the files an agent changes take space, and build output such as node_modules or target comes along already built. On other drives (ext4, NTFS, exFAT) each copy is an ordinary checkout, as before. Either way a copy starts exactly at its branch, without your uncommitted changes.

flowchart LR
  P["Project folder, your branch"] -- "copy from the last commit" --> A["Builder's copy, own branch"]
  P -- "copy from the last commit" --> B["Tester's copy, own branch"]
  A -- "Merge" --> P
  B -- "Merge" --> P

The Git page lists them under Agent copies. Each shows its branch, the commits to merge, and its uncommitted files.

ButtonWhat it doesWhen it's off
MergeBrings the agent's work into the project's current branch. Its uncommitted changes are committed on its branch first.While the agent runs ("Stop this agent first"), or when there is nothing to merge
Remove copyDeletes the copy's folder. The branch is kept.While the agent runs, or while it has uncommitted work ("Merge first: it has uncommitted work")

Next steps