agit

Lossless version control for every agent session: publishable, resumable. Works with Claude Code, Codex, OpenCode, and Cursor.

On disk, sessions are just JSONL files that get overwritten, compacted, and cleaned up at any moment. agit puts snapshots and versions on top of them, so "that conversation last Wednesday that finally cracked the bug" becomes something you can find, continue, and hand to a teammate.

agit                              choose a session to continue
agit new                          choose a repo and name a fresh conversation
agit import                       choose an existing runtime conversation to adopt
agit log                          choose a session and browse its history
agit push                         choose a saved session to publish
agit share                        choose a session and review link settings
agit run owner/repo@ref           open a saved source, forking when needed

These bare commands open their interfaces in a human terminal. agit resume continues the same session and never forks; agit run can start a new writable session from a tag, historical point or another author's source.

Inside an adopted agent session, agit commit saves completed turns and agit push publishes that session. For scripts, pass the target explicitly, for example agit push owner/repo@branch --json. Directory branch pins do not choose targets for commit, push or share.

On user-facing startup, agit checks for a newer release at most once a day and prints a reminder to stderr; it never upgrades automatically. JSON/quiet/CI and internal hook/MCP paths skip this reminder.

Adopting and recording the first version are one command — the in-between state ("linked, but unversioned") means nothing to anyone. To mark a session without versioning it (e.g. offline), pass --link-only.

Use a full native session ID and an explicit runtime and destination for lineage discovery. The terminal offers verified local bases, independent import, or cancellation. Noninteractive calls return choices without writing; pass --onto <ref> or --independent to select a path. --propose-lineage prints a read-only report without adopting the session. Inspecting lineage in an existing repository requires NUL-framed Git worktree output, normally available in Git 2.36 or newer. An unsupported Git reports git_worktree_format; explicit --onto, --independent, and --link-only imports retain their ordinary checks.

agit clone fetches repository history locally. Use agit run or agit resume to start a runtime. A clone is read-only by default on the Hub: nothing is created in your name and origin points at the source. agit clone --mine creates your copy, repoints origin and remembers the source as upstream.

The full command list is in agit --help.

Install

Users: npm

npx -y create-agit@latest          # one-shot: installs agit + wires skills/hooks/MCP
# or as a global package:
npm install -g @einsia/agent-git --allow-scripts=@einsia/agent-git
agit --version

Both routes install a prebuilt binary — no Rust toolchain required. npm picks the platform sub-package matching your os/cpu; on platforms with no prebuilt binary (e.g. FreeBSD) running agit prints the source-build recipe. Details and environment variables: npm/README.md.

Windows x64 packages include the native peer RC daemon. On Windows, Linux and macOS, run agit login followed by agit rc start --detach to register the device and allow your own account to control it from Workspaces. Windows owner RPC uses a local named pipe restricted to the current user. RC state requires a private, user-owned directory.

The global package wires skills, hooks and MCP from its install script. npm 12 and later skip an install script that has not been allowed, which is what --allow-scripts above is for; an organization policy (strict-allow-scripts, ignore-scripts) can block or skip it too. Under pnpm (pnpm add -g @einsia/agent-git) the install script configures nothing. If the install script did not run, run agit setup once yourself. It sets up the runtimes installed at the time, so run it again after installing another.

The Linux artifact is musl static-linked, so no minimum glibc — the release pipeline runs every Linux binary inside an Alpine / Amazon Linux / Debian / Ubuntu container matrix before publishing.

Prebuilt binaries include Git and Git LFS, extracted into a private cache on first use. Your shell PATH and global Git configuration stay unchanged. Source builds use system Git; AGIT_USE_SYSTEM_GIT=1 selects it in a prebuilt binary too. See runtime configuration and source prerequisites.

Do not install @einsia/agentgit (no hyphen) — that is the pre-rewrite CLI; its protocol does not match this branch and it will not work.

Contributors / eager users: from source

git clone https://github.com/Einsia/agent-git
cd agent-git
./setup.sh

setup.sh checks the toolchain (rustc, a C compiler), builds, and installs the binary to ~/.local/bin/agit. Common flags:

./setup.sh --debug      # no LTO, much faster while hacking
./setup.sh --test       # run cargo test --lib before installing
./setup.sh --help

To build a binary whose built-in hub is the staging deployment, set the build-time default explicitly. Runtime AGIT_HUB_URL and agit config hub.url ... still take precedence:

AGIT_DEFAULT_HUB_URL=https://staging.agent-git.com cargo build --release --locked

Internal GitLab pipelines package commit-addressed dev and staging builds with this setting embedded. Their agit --version output includes the channel and source commit, and agit upgrade is disabled for them so an acceptance-test binary cannot silently turn into the public release. Only an existing GitHub agit-v* tag produces the prod channel. The tag push runs the Release workflow automatically; operators may also select the same reviewed tag through the workflow's manual production input to retry a failed release without creating a different artifact identity.

Requires rustc >= 1.88 and a C compiler (rusqlite uses the bundled feature, so sqlite's C sources are compiled during the build). The reason for the toolchain floor is in docs/01_setup.md.

Both paths install the same binary. npm is for "users who don't want to touch Rust"; setup.sh is for "people changing the code" and "people running unreleased versions".

Docs

The server (AgentGit) is a separate repository, deployed on its own.

Release

Cargo.toml is the single source of the version; every npm manifest must agree with it (node scripts/check-version.js — run in CI and before npm pack). To move the version, change every spot in one shot:

node scripts/bump-version.mjs 0.1.0    # Cargo.toml + Cargo.lock + all npm manifests

Release notes live in CHANGELOG.md, and they come first: write the version's ## [x.y.z] section, then bump. bump-version.mjs refuses to touch a file for a version that has no section, and check-version.js refuses one in CI and before npm pack. The section becomes the GitHub Release body (scripts/release-notes.mjs extracts it in release.yml, with repository-relative links pinned to the release tag) and ships inside the @einsia/agent-git package.

Only the release branch (release/<version>) edits CHANGELOG.md. Every other merge request puts one line per user-visible change in its description, or Changelog: none:

Changelog: Added|Changed|Fixed|Security: <one sentence for users>

The release branch collects those lines into the version's section. CI's changelog:released fails any other merge request that changes the file: a line it adds under ## [Unreleased] can merge into a released section without a conflict.

After the release merge request passes CI, merge it into GitLab main while its head contains main's tip, and merge nothing else until the tag exists. Wait for that pipeline's mirror:github, then run its manual release:github-tag job. CI refuses a release commit whose tree is not the release merge request's head, verifies the recorded source-to-mirror mapping and creates agit-v<version> on the public mirror commit. Release tags are immutable; a stale pipeline cannot publish after either main moves.

mirror:github does not wait for the main pipeline's Windows build. Windows is checked by every merge request's rust:test:windows, which for the release ran on exactly the tree being released, and again by the GitHub Release workflow before npm.

The mirror rewrites commit IDs, so the source SHA is not the release SHA. Do not push release tags directly to GitHub. The CI-created tag starts the GitHub Release workflow, which builds and checks the binaries of every target, Windows included, and then triggers npm publication.

Distribution to users runs through the npm registry: each target ships as a platform sub-package (@einsia/agent-git-linux-x64 and friends, gated by os/cpu — npm installs only the matching one), and the main @einsia/agent-git pulls them in via optionalDependencies. The GitHub Release holds the canonical tarballs plus SHA256SUMS (contract).

Publishing to npm is the npm publish workflow. It runs automatically once the Release workflow finishes green (and can be dispatched manually — Actions → npm publish — for retries, next dist-tag trials, or a dry_run). It publishes the whole family in dependency order — platform packages → @einsia/agent-git → create-agit — with a real global install of the main tarball as a preflight in between, authenticating via npm trusted publishing (OIDC, no stored token). The equivalent local fallback:

gh release download agit-v0.1.0 -p 'agit-*.tar.gz' -D /tmp/agit-dist
node npm/publish.mjs /tmp/agit-dist        # platform packages → main → create-agit

npm/create-agit/ is the one-shot installer behind npx -y create-agit@latest — it depends on the main package and turns the npx cache copy into a durable ~/.local/bin/agit, then wires skills/hooks/MCP via agit setup. There is deliberately no unscoped alias package: agit on npm belongs to an unrelated project, and npm's typosquat rule blocks agent-git for being one punctuation mark away from a third party's agentgit.

The version oracle (GET /api/cli/version on the hub) and agit upgrade both read the npm registry; integrity verification uses the registry's SRI (sha512). Self-hosted hubs that pin an internal fork set AGIT_BACKEND_CLI_REPO and the whole chain reverts to the GitHub path.

@einsia/agent-git is a fresh package name with no existing users, so the first release goes straight to latest — no need to hide in next first. (The old @einsia/agentgit stays put; it points at the pre-rewrite CLI.)