Docs / Guides

Working with AI agents

sgit is designed to be driven by AI agents as well as humans. A vault is just a folder — the agent reads and writes files normally; sgit handles versioning, encryption, and sync. This page covers the agent-facing surface.

The session pattern

# start of session: get the workspace
$ sgit clone <vault-key> workspace   # or: sgit pull, if already cloned
# … agent works on files normally …
# end of session: persist the state
$ sgit commit -m "session: findings and next steps"
$ sgit push

The next session — hours or weeks later, on any machine — runs sgit pull and continues. State survives the context window, encrypted end to end.

sgit write — the surgical commit

When an agent needs to record one result, cloning a whole vault is waste. write commits a file directly to the vault HEAD in a single call: no working-directory scan, no full clone needed.

$ sgit write notes/finding.md --file result.md \
    --message "agent A: analysis" --push --json
{ "status": "pushed", "path": "notes/finding.md",
  "blob_id": "obj-cas-imm-9c2e41ab77d0" }

• --also vault-path:local-file (repeatable) makes a multi-file write atomic — one commit, all or nothing.
• Content-hash dedup: writing identical content returns unchanged and creates no commit.
• --json gives a machine-readable result for the calling pipeline.

Machine-readable everything

Fast cold starts

Agents run on time budgets. Three clone modes keep startup cheap:

• sgit clone --sparse — structure now, file content on demand via sgit fetch <path>.
• sgit clone-branch — full history, but only HEAD's content.
• sgit clone-headless — credentials only: derive keys and write config, fetch nothing.

Multi-agent collaboration

Give each agent a named branch; the two-branch model guarantees isolation of work-in-progress. Two commands make peer review safe:

• sgit history show <commit> and sgit history diff are read-only — they fetch missing objects on demand without merging, so an agent can inspect a peer's commit without touching its own working copy.
• sgit resolve --show renders base/ours/theirs with a per-file verdict, so genuine conflicts are distinguishable from noise — by a human or by an agent.

# agent A  $ sgit branch new feature-analysis … commit … push
# agent B  $ sgit history show obj-cas-imm-c4e81a   # look, don't merge
# human    $ sgit pull → review in SG/Vault → merge