Skip to content
safegit Requirements
Updated Edit
On this page

Requirements for safegit: multi-agent concurrency safety, lock-free design, standard Git compatibility, CLI and hooks support, and crash recovery.

#safegit Requirements

Historical document. This is the original requirements list, kept as the record of what safegit was asked for. It is not a description of the built tool, and where the two differ the implementation is the authority -- see Architecture and the Concurrency Guide. One difference is worth naming here, because the requirement below states the opposite: the lock does poll. Waiters use exponential-backoff polling (10ms to a 1s cap, bounded by lock.acquireTimeoutSeconds), with the backoff reset whenever the lock is observed to have changed hands. No notification mechanism was built; the requirement's real goal -- that no human has to intervene -- is met by automatic stale-lock reclamation.

#Core: Multi-Agent Safety

  • Multiple AI agent sessions must be able to work on the same repo concurrently without worktrees
  • No shared mutable staging area -- agents must not be able to stage or commit each other's files
  • Commits must be serialized or isolated so that concurrent commits never produce corrupt or mixed results
  • If two agents edit the same file, the conflict must be surfaced as data, not silently lost or merged

#Concurrency Mechanism

  • Lock-free or minimally-locking design preferred over a global mutex
  • If a queue/lock is used, it must notify waiting agents automatically (no polling, no human intervention) (as built: polling with backoff, no notification -- see the note at the top)
  • Agent crash must not leave the repo in a permanently locked state (stale lock recovery within 30 seconds)

#Git Compatibility

  • Must read and write standard .git repositories
  • Commits must be normal git commits (same SHA, same format) visible to any git tool
  • Push/pull to GitHub, GitLab, and any standard git remote must work
  • Teammates using plain git must see normal branches and commits
  • CI/CD pipelines and code review tools must work without modification

#CLI

  • Must be usable as a CLI tool (no GUI dependency)
  • Must support non-interactive / headless operation for agent consumption
  • Structured output (JSON) for agent parsing is preferred

#Hooks

  • Pre-pre-push hooks: ability to run hooks before a connection to the remote is even established (e.g. validate, lint, or gate before any network I/O to GitHub)
  • Git's built-in pre-push hook fires after the remote connection is already open -- this is too late for some use cases (e.g. smoke tests that take a long time will cause the already-open SSH connection to timeout)

#Reliability

  • Every mutating operation should be undoable *(as built: safegit undo reverses every operation safegit's own commit pipeline authored -- a commit, an amend, a reword, an mv, a merge, pull, cherry-pick or revert that ended in a commit, and the three conclusion commands -- by moving a ref. It moves no working tree, it does not restore the git operation state a conclusion removed, and it refuses to roll a branch back over a commit safegit did not author: a fast-forward's tip, a passthrough's commits, and the commits git writes when a rebase replays them or when a queued sequence started with raw git is concluded through git's own --continue. A history rewrite invalidates every earlier oplog entry and blocks undo outright)*
  • No operation should silently lose work
  • Crash recovery must be automatic or trivial

More tools from this site

  • claudestream Drive Claude Code from Python: run it as a subprocess and read its output as typed events, with async and sync sessions, sandbox policies, and tools you define in Python
  • claudewheel A TUI Claude Code Launcher that lets you have more than one profile, manage sessions lifecycle, pick the exact CC version, model to use (even older unlisted ones), pick which GitHub account to use, etc.
  • dirstat Fast, single-binary directory statistics CLI: every file under a tree grouped by format, with counts, sizes, and lines of code, as a colored terminal table or as JSON
  • fastware A batteries-included ASGI framework: msgspec JSON, a managed Granian server, dependency injection, SSE, WebSockets, auth, and a test client
  • go-toml-edit Zero-dep TOML editing library for Go with comment preservation
  • howmuchleft The fastest Claude Code statusline: context window, 5-hour, and weekly limit usage as three customizable gradient bars, rendering in about 6 ms
  • orxtra
  • pgdesign
  • predraw Declarative rendering pipeline: describe a scene in JSON and get SVG, PNG and WebP out, with light and dark style tokens, reusable components and text converted to path outlines
  • reposummary Turn a git repository's history into a Markdown journal: pick a time window or revision range and get a readable digest of what changed, optionally narrated by an LLM
  • rlsbl Release orchestration and project scaffolding CLI that bumps versions, validates a structured JSONL changelog, tags only the commit CI verified, and publishes to npm, PyPI, Go and more
  • saferm Command-line replacement for rm that archives every deletion with a mandatory reason and the context it ran in, so deleted files can be listed, inspected and restored
  • selfdoc Static Site Generator that builds a project's documentation site directly from its source code, so the docs can never drift from the code they describe, with SEO/AEO, first-class blog, search, and cross-project linking built in
  • strictcli
  • stricttest An always-on test-isolation floor: a pytest plugin and a Go env-hygiene module that make a test suite structurally unable to reach real credentials, the real HOME, the network, or the development repository.
  • wesktop A Python framework that turns an ASGI web app into a desktop application, serving it from a local Granian server and displaying it in a native OS window via pywebview
Search