Every session gets its own APFS clone. The base stays shared.

Two programs, one socket

The socket is ~/Library/Application Support/git-strata/daemon.sock. With the daemon stopped, status, grep, files, diff, deps list, and daemon status still read the store. Repeating a checkpoint --tool-call whose checkpoint already exists also works. Every other command returns Busy with reason daemon_down.

The session loop

1. Create the session

   git-strata new with --repo for each repo you want tracked. Those repos are fetched and get a workspace. The session id and the workspace paths come back on the JSON line, under data.manifest. The older --repos form, with no --repo, gives every repo in config.toml a workspace and tracks the names you list. Do not edit an untracked sibling. That edit is never checkpointed.

2. Edit the workspace

   Work in data.manifest.repos.<repo>.path. Commands without --session take the session from the current directory. --session accepts an id or a ticket.

3. Record a checkpoint

   git-strata checkpoint -m records the edits. A hook can send checkpoint --tool-call. status, diff, grep, and files inspect the session, including other sessions with --all or --session. There is no search command: grep searches content, files lists paths. restore rolls a checkpoint back.

4. Publish the paths you name

   git-strata publish --from SESSION:PATH commits those checkpointed paths onto refs/strata/publish/<branch>. The manual's sequence leaves the workspace before publish. In zsh, write "${S}:path". "$S:path" is a history modifier and silently changes the string.

5. Push only when that is the ask

   git-strata push REPO updates the remote. If the repo's publish.push is on, publish itself pushes. A gated repo waits for a person at a terminal.

6. Remove the session after it is published

   git-strata rm --session removes the session once its work is published. Unpublished work makes rm return Dirty, and nothing is removed. rm --discard is a human command.

Each session leases four TCP ports, web, connector, connector_mcp, and aux, so concurrent dev servers do not collide. session exec runs a command in the workspace with PORT and the STRATA_* port variables set. The main checkout keeps the project's own ports.

Every call prints one compact JSON line with ok, data, and error. Branch on error.code. Do not parse the message. Help, --help, and --version print plain text.

git-strata daemon status
git-strata new PROJ-123 --repo tool --repo billing-api
# S = data.manifest.id
# W = data.manifest.repos.tool.path
git-strata add --session "$S" --repo front
cd "$W"
git-strata checkpoint -m "parse config before connect"
git-strata diff
cd ~
git-strata publish --from "${S}:src/a.ts" --from "${S}:src/lib"
git-strata rm --session "$S"

Install the formula, then write the agent

The Homebrew formula installs prebuilt binaries and a sample config.toml. It is Apple silicon only, macOS Ventura or later. The project itself also runs on Intel when you build it from source. Homebrew does not quarantine these formula binaries, so they need no xattr step.

1. Install with Homebrew

   Tap first, then install the formula named in the tap README and in the project manual.

   brew tap dickwu/tap
   brew install dickwu/tap/git-strata

   Copy

2. Write the LaunchAgent and the config

   Point the plist at the stable Homebrew opt path so an upgrade does not need a plist edit. Copy the sample config, then set [paths] root to a directory on the same APFS volume as your repos. The default ~/.strata works only when those repos are on the startup volume. Edit the file before you start the daemon.

   mkdir -p ~/Library/LaunchAgents
   t=$(mktemp ~/Library/LaunchAgents/.git-stratad.XXXXXX) \
     && git-stratad --print-plist "$(brew --prefix)/opt/git-strata/bin/git-stratad" > "$t" \
     && mv "$t" ~/Library/LaunchAgents/com.gwd.git-stratad.plist
   mkdir -p ~/Library/Application\ Support/git-strata
   cp "$(brew --prefix)/share/git-strata/config.toml" \
     ~/Library/Application\ Support/git-strata/config.toml
   # edit config.toml ([paths] root on the same APFS volume as your repos), then:
   git-strata daemon start

   Copy

3. Restart after an upgrade. Stop before you uninstall.

   After brew upgrade git-strata, stop the daemon and start it again. Upgrading an existing data root to 0.2.0 migrates the store forward. Read the v0.2.0 release notes before you upgrade. Before brew uninstall git-strata, stop the daemon and remove the plist, or launchd keeps restarting a missing binary.

   git-strata daemon stop && git-strata daemon start

   Copy

   git-strata daemon stop
   rm ~/Library/LaunchAgents/com.gwd.git-stratad.plist
   brew uninstall git-strata

   Copy

npx skills add dickwu/git-strata --skill git-strata -g -a claude-code -a codex -a cursor -y

A push can wait for Touch ID

This page is the CLI

GIT STRATA Desktop is a separate Homebrew cask, brew install --cask dickwu/tap/git-strata-desktop. It drives the daemon from this formula. Its site is git-strata-desktop.lifefarmer.ca. Both sit in the lifefarmer catalog.

Questions