An AI-native version control system that uses an operation graph to manage concurrent edits from humans and AI agents with deterministic merging.
Also known as izagood/avcs, @izagood/avcs
- Stars
- 1
- Tools
- 39
- Downloads, 30 days
- 556
- Latest version
- 0.42.0
- Last commit
- Oct 24, 2026
- License
- Apache-2.0
What is AVCS MCP?
AVCS is an AI-native version control system that uses an operation graph to manage concurrent edits from humans and AI agents with deterministic merging. It exposes 39 tools, such as avcs.guide, avcs.governance.status, avcs.approval.record.
Summary generated from the project's README
About AVCS MCP server
Managing concurrent code edits from both humans and AI agents is what AVCS enables through an operation-graph-based version control system. Unlike traditional tools that track file snapshots, this system stores intent, sessions, and operations as first-class objects to ensure deterministic merging. It is designed to reduce the token cost for AI agents by focusing on the size of the change rather than the size of the entire file, which significantly lowers the overhead during conflict recovery.
Developers and AI agents use this system locally or against a server to maintain a single source of truth that is a projection of an operation DAG. The system uses a deterministic reducer and policy engine to handle conflicts through various levels, ranging from automatic merges of disjoint regions to requiring human decisions for public API breaks. It requires no git dependency for its core functionality, though bridges exist for interoperability. Users interact with the system via tools like avcs undo for local history management and specific MCP profiles to minimize tool schema overhead.
What you can do with it
- 1Automate conflict resolution with policyA developer can set rules so that overlapping edits are resolved via a policy-based auto-decision rather than manual conflict markers.
- 2Gate changes with machine evidenceAn AI agent can be prevented from merging a behavior change if it does not include passing test evidence.
Written from the project's README. Every use case is checked against a quote from it.
How to install AVCS MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall AVCS MCP in Claude Code
$ claude mcp add avcs -- npx -y @izagood/avcs mcpInstall AVCS MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"avcs": {
"command": "npx",
"args": [
"-y",
"@izagood/avcs",
"mcp"
]
}
}
}Install AVCS MCP in VS Code
.vscode/mcp.json
{
"servers": {
"avcs": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@izagood/avcs",
"mcp"
]
}
}
}Install AVCS MCP in VS Code CLI
$ code --add-mcp '{"name":"avcs","type":"stdio","command":"npx","args":["-y","@izagood/avcs","mcp"]}'Install AVCS MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"avcs": {
"command": "npx",
"args": [
"-y",
"@izagood/avcs",
"mcp"
]
}
}
}Install AVCS MCP in Codex
$ codex mcp add avcs -- npx -y @izagood/avcs mcpInstall AVCS MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.avcs] command = "npx" args = ["-y", "@izagood/avcs", "mcp"]
Install AVCS MCP in Gemini CLI
$ gemini mcp add -s user avcs npx -- -y @izagood/avcs mcpInstall AVCS MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"avcs": {
"command": "npx",
"args": [
"-y",
"@izagood/avcs",
"mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @izagood/avcs 0.42.0 in an isolated container with no network and no keys. It answered and listed 39 tools.
AVCS MCP tools 39
Read from the server with tools/listavcs.guideHow to use AVCS: the canonical loop, agent rules, tool index, error recovery. Call this first.
avcs.governance.statusRead-only review state for a view: protection rules, head, your role, and the effective approvals.
avcs.approval.recordRecord a reviewer verdict on a checkpoint, signed with the reviewer's local key. Requires role >= reviewer.
avcs.context.buildAssemble working context for a scope under a byte budget: provenance, decisions, risks, history. Deterministic truncation.
avcs.decision.recallPrior human decisions for a conflict key plus the policies they taught. Read precedent before re-deciding.
avcs.sync.pullPull objects from the hub (conflict-free gossip). dryRun reports what would arrive without importing.
avcs.sync.pushPush local objects to the hub. Returns how many were accepted and how many the gate rejected.
avcs.sync.landLand work on a protected head in one call: push, merge-check, checkpoint, integrate. Result is landed or a conflict packet.
avcs.workspace.projectWrite a view to a directory on disk, so build/test loops outside validate.run need no CLI.
avcs.key.provisionMint a local signing key for an actor so its decisions and hub writes can be signed. Idempotent.
avcs.key.listWhich actors this machine can sign as, and which public keys the repo trusts. Ids only, never key material.
avcs.intent.createOpen an intent: the goal + constraints + allowed scopes for a unit of work. Agents must work within an intent.
Show all 39 toolsShow fewer tools
avcs.intent.readRead an intent (goal, constraints, allowed scopes). An agent should read this BEFORE proposing operations so it works within the constraints.
avcs.intent.listList intents in the repo. Bounded: limit (default 50).
avcs.session.startBegin a work session for an agent/human against an intent. Returns a session id used on every operation.
avcs.operation.proposePropose a semantic change (MVP: file writes). Declare effects honestly — policy gates on them. baseText/baseBlobOid authors a 3-way-mergeable edit_file.
avcs.contention.checkOther actors' live concurrent ops and overlapping lease holders for given keys. Run while editing, so overlap surfaces before finalize.
avcs.workspace.landLand a workspace onto its base line: its isolated ops join the base view and merge there. Idempotent.
avcs.workspace.listList this repo's workspaces: `workspaces` names them all, `landed` the subset joined onto the base view. The rest stay isolated.
avcs.line.createFork a long-lived line (e.g. 'v1.x') from another at its current state. It inherits history to the fork, then diverges.
avcs.line.listList the lineage lines in the repo (besides the implicit 'main').
avcs.operation.backportCherry-pick an operation onto another line: mints a new op carrying the change, with derivedFrom provenance. Source line untouched.
avcs.evidence.attachAttach machine-checkable evidence (test/typecheck/lint/...) to operations. Behavior changes need a passing test to be accepted.
avcs.view.materializeReduce a view's operation graph into a tree, per-op status and open conflicts — how an agent checks that its work merges.
avcs.conflict.listList the conflicts that require a human/owner decision in a view.
avcs.decision.recordRecord a human owner's conflict resolution. Owner-confirmed and signed with their local key; an agent cannot forge it.
avcs.checkpoint.createFreeze a verified (ops + policy + materializer + evidence) state vector for a view.
avcs.integration.submitSubmit a checkpoint to the integration queue. Verdict is advanced, conflict, needs_evidence or queued — never 'pull and redo'.
avcs.integration.statusIdempotent lookup of an integration ticket's recorded verdict on a remote hub (polling companion to avcs.integration.submit).
avcs.lease.requestRequest a soft write-lease over entity scopes BEFORE editing, to avoid duplicating another agent's in-flight work. Returns the lease oid, or the conflicting holders.
avcs.validate.runRun validation commands against a view and attach treeHash-bound evidence. Pass dir to reuse an existing build environment.
avcs.repair.contextMinimal repair packet for ops whose validation failed: failing output, related decisions, a fix instruction. Cheaper than re-reading the repo.
avcs.metricsIn-process metrics snapshot for this server (reduce cache hit/miss, reduce.ms timing, materialize.calls).
avcs.blameWho currently owns an entity (file:<path> or symbol:<path>#<name>) and WHY — the accepted head op with actor, intent title, and purpose. Stronger than git blame.
avcs.blame.linesPer-line provenance: the op that last wrote each line, with actor, intent and purpose. Why THIS line is here.
avcs.historyHistory of one entity in causal order. Paged: limit (default 20) + cursor.
avcs.diffDiff two views/lines. format 'paths' (default) or 'patch' (unified diff).
avcs.release.cutCut a release: a conflict-free checkpoint plus evidence, SBOM and artifact references. Refuses if the view has open conflicts.
avcs.object.showRead an object by oid. Blobs return decoded content (utf8 text or base64); other types return the structured object.
Configuration
AVCS_CONFORMANCE_URLAVCS_HUB_TOKENAVCS_REPOabsolute path of the AVCS repo to serve; defaults to the client cwd
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableizagood/avcs is public and reachablegithub.com/izagood/avcs ↗Pass
- Package names this repository as its source@izagood/avcs names izagood/avcs as sourcenpmjs.com/package/@izagood/avcs ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @izagood/avcsnpmjs.com/package/@izagood/avcs/v/0.42.0#provenance ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-24github.com/izagood/avcs ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @izagood/avcsPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAVCS — Agentic Version Control System
An AI-native version control system for humans and AI agents working concurrently.
An agent should not spend its context on version control. That is the whole design goal, and it is measured rather than asserted — here is what the same work costs an agent:
| What an agent pays for | git / the full surface | AVCS |
|---|---|---|
| Landing a change after someone else's PR merged first (30 KB module) | 18,922 tokens | 279 tokens — 99% less |
| Round trips to finish that recovery | 7 | 4 |
| Tool schema, paid on every session | ≈8.8k tokens (39 tools) | ≈3.5k tokens (13, --profile core) |
| What a same-line collision hands the model | the whole file, with conflict markers | one object naming the two contending operations |
git's recovery cost tracks the size of the file — a conflict is bytes inside it, so the agent reads the whole module and writes the whole module back to change one line. AVCS's tracks the size of the change: a conflict is an object naming the two contending operations, so it stays flat as the file grows. There is also no branch to rewrite and nothing to force-push, which is why the round trips differ — and that is one cycle, repeated for every PR that merges ahead of yours. Across the file sizes measured the saving is 37–99%.
None of this is a compression trick bolted on afterwards. It falls out of storing the operation graph instead of snapshots: there is no rebase to perform, so there is nothing to re-read. Method, caveats and the harness that produced the rebase numbers: avcs-demo → what it costs an agent in tokens. The schema figures are the advertised MCP surface itself — 35 KB of JSON against 14 KB, at the usual ≈4 bytes per token.
Git records when the code changed. AVCS records who changed it, with what intent, on what evidence, and through which conflict decisions the code reached its current state.
AVCS is a new, deliberately Git-incompatible version control system built for a world where humans and many AI agents edit the same codebase concurrently. It drops the commit / branch / merge / conflict-marker model and instead stores intent, session, operation, evidence, and decision as first-class objects. The code tree is not the source of truth — it is a projection computed by deterministically reducing the operation graph:
state = reduce(base, operationDAG, decisions, policy, materializer)
The same objects + the same policy + the same materializer produce the same tree on any replica. Merging is not text selection; it is a pure, deterministic reduction.
Status: research prototype. The implementation is real and test-covered, but every phase is built to a working-MVP depth (language-neutral text 3-way merge, ed25519 signing). Structure-aware merge, semantic-break detection, multi-signature trust, and hardened distributed sync are tracked on the roadmap.
Jump in: install · your first five minutes · work against a server · connect an agent over MCP · agent quickstart walkthrough
See it run first: izagood/avcs-demo — a runnable
demo of the question this design answers: what happens when two agents edit the same file at
the same time? One ./demo.sh walks a stale-head land that is absorbed instead of rejected,
a same-file auto-merge with no rebase, and a same-line collision that becomes a signed
decision rather than conflict markers.
Why not a layer on top of git?
Every "AI + git" tool eventually stores the agent's context beside the history — commit trailers, PR comments, sidecar JSON. AVCS exists because these objects have to be load-bearing — consumed by the merge machinery itself — and bolted onto git they can't be:
- Evidence must gate merging. git happily merges a behavior change with no passing test. In AVCS that change is graded L3 — blocked by the reducer until trusted evidence lands, and an operation's own author vouching for it does not count.
- Decisions must outlive the merge.
git mergeresolves a conflict by emitting bytes; the choice and its rationale evaporate. An AVCSdecisionis a signed object — recallable later, and prior decisions bias future auto-resolution. - Concurrent edits must not degrade into conflict markers. Two agents editing one
file meet a deterministic policy reduction (L0–L4 below), not
<<<<<<<in the tree plus a human holding the pieces. - Intent must travel with the work. A trailer is inert text. An
intent(goal + constraints + allowed scope) is what sessions open against, what leases and contention checks are scoped by, and whatavcs.context.buildhands the next agent.
git stores snapshots and leaves the merge to text selection; AVCS stores the operation graph and makes the merge a computation over intent, evidence, and decisions. That is why it is deliberately git-incompatible — these objects are the engine, not metadata. (git interop still exists, as a bridge: docs/14, docs/20.)
Core principles
| # | Principle | Contrast with Git |
|---|---|---|
| 1 | Operations are history, not commits | A commit is merely a checkpoint over many operations |
| 2 | Identity is the entity ID, not the file path | Rename + edit can auto-merge |
| 3 | Merge is a deterministic reduction, not text selection | No conflict markers |
| 4 | A conflict is a first-class decision object, not a broken file |
The rationale stays in history |
| 5 | AI output is a proposed operation with attached evidence, not trusted code | A behavior change with no test cannot be accepted |
| 6 | Code never defaults to last-write-wins | Precedence is decided by policy |
How it works
Every meaningful thing is a content-addressed, append-only object. Code is a projection over the operation DAG, never stored as commits.
| Object | Role |
|---|---|
intent |
Why a change is being made (goal + constraints + allowed scope) |
session |
An agent/human work episode against an intent |
operation |
A single semantic change unit — the real history |
evidence |
Machine-checkable proof (test / typecheck / lint / scan) attached to operations |
decision |
A recorded resolution of a conflict or design choice |
checkpoint |
A verified (ops + policy + materializer) state vector — replaces a commit |
view |
A declarative query over the operation graph — replaces a branch |
release |
A signed, provenance-bearing checkpoint — replaces a tag |
policy |
The deterministic merge rules the reducer is parameterized by |
…plus blob for raw content and the governance objects (lease, membership, protection, promotion, redaction, override, approval, line, integration) used by the multi-machine and security phases.
Conflict resolution levels
AVCS never falls back to last-write-wins for code. Contending operations are graded and resolved with a recorded rationale:
- L0 / L1 — different entities, or disjoint line regions in the same file → auto-merge
- L2 — concurrent edits that overlap the same line region → policy auto-decision (human-preferred, trust-weighted); the auto-decision is itself recorded in
autoDecisions - L3 — a behavior change with no trusted evidence → blocked
- L4 — a public-API break → requires a human decision, routed to the scope's owners
Evidence trust matters: an operation's own author cannot vouch for it. Evidence-gating and the passing-test bonus only count evidence produced by a non-authoring, trusted actor (CI bot / human).
What works today
The reducer and policy engine are the foundation; the higher phases build distributed collaboration, security, and observability on top.
Foundation (Phases 1–6)
- Storage core — append-only, content-addressed object store (
.avcs/objects) - Deterministic reducer + policy engine — the L0–L4 conflict grading above, with a priority ladder, bounded reliability nudges, and auditable auto-decisions
- Language-neutral text merge (Phase 2) — a deterministic N-way line-level 3-way merge (
src/merge/merge3.ts), so edits to disjoint regions of one file auto-merge regardless of language; overlapping edits become a policy-resolved conflict region. No language parsing in the core - Cryptographic trust (Phase 3) — ed25519-signed evidence/decision; forged signatures fail the trust gate. Real validation runner,
WorkLease,RepairContext - Decision memory (Phase 4) — recallable prior human decisions (
recallDecisions) and distilled "learned policies" that bias future auto-resolution - Policy depth (Phase 5) — code-owner routing and bounded reliability learning
- Release & provenance (Phase 6) — verified checkpoints + CycloneDX SBOM + signed artifacts
Collaboration, scale & security (Phases 7–12)
- Phase 7 — multi-machine: membership/roles (signed key federation),
pull(object gossip; two replicas converge to the sametreeHash), protection +finalizeCAS (non-fast-forward rejected, so a stale push can't overwrite fresh history) - Phase 8 — lineage: long-lived divergent lines (e.g. v1.x ∥ v2.x, same path, different content, zero conflict),
portOp(backport = cherry-pick) - Phase 9 — scale: entity index,
materializeAt(time travel), chunked large-blob storage with dedup - Phase 10 — observability:
blame(who/why),logP, deterministicbisect,diff - Phase 11 — external contributions: quarantine tier +
promote+ untrusted-CI gate - Phase 12 — security:
redact(byte-eviction of leaked secrets, oid preserved), break-glassoverride, forward-only rollback - Local undo (docs/23) —
avcs undo [--last | <op-oid>…] [--purge] [--no-git]: drop local ops from the view, and with--purgeevict the bytes they uniquely reference. Refuses once the ops have been pushed, because that case belongs to admin-gatedredact. In a git-bridged repo--purgeclears the git copy too — but only where it can prove the rewrite is safe and local (nothing on a remote, the commits at the tip, no other work in them, a clean tree); anywhere else it still does the AVCS side and names precisely what is left and the one command that fits, up to and including "rotate the credential, it is already published" - The working tree is genuinely derived —
checkoutrecords what it projected (.avcs/projection.json, path → blob oid) and, on the next projection, removes the files the target view no longer contains. Files it never wrote — build output, ignored files, anything you just created — are untouched, and a projected file you have since edited is kept and named in a notice rather than silently overwritten. Switching views therefore yields that view, not the union of every view projected before it
Branches become views, commits become checkpoints, tags become releases. Agents drive AVCS through a first-class MCP server (39 tools, or 13 with --profile core); humans use the CLI. Since Phase 14 the server runs an integration queue (avcs submit, POST /integrate): a stale submission is never told "head moved — pull first" — the server re-reduces the frontier union on the submitter's behalf, and the outcome is always a verdict (advanced | conflict repair packet | needs_evidence — one validation run, never a redo | queued). Since Phase 15 replicas converge live (GET /events long-poll, avcs sync --watch, contention early-warning), and Phase 16 completed the MCP surface: avcs.sync.land lands work in one call, avcs.context.build assembles bounded working context with deterministic truncation, and subscribable resources notify a client when the head moves — see docs/17 and docs/18. The behavior is pinned by an 827-test contract suite (test/*.test.ts, all green) and tsc is clean.
Install
Requires Node ≥ 22.6 — AVCS runs TypeScript directly via type stripping, so there is no build step and zero runtime dependencies.
AVCS is published on npm as @izagood/avcs. Install it globally to get the avcs command on your PATH:
npm install -g @izagood/avcs
Or run it without installing, straight from the registry:
npx @izagood/avcs version
Your first five minutes (no server, no git required)
AVCS is local-first: a repo on your disk is a complete VCS — history, blame, undo, releases — with no server and no git anywhere. In an existing project directory:
avcs init . # create the repo (inside a git repo is fine — .avcs is git-ignored)
avcs import . -m "initial import" # bring the existing tree in as operations
# …edit files as usual, then record the change:
avcs commit -m "add mul()" # authors operations for your working-tree changes
avcs status # operation / conflict summary
avcs log # operation history
avcs blame file:src/math.js # who owns this file and why (entity key = file:<path>)
avcs conflicts # decisions a human still owes
avcs decide <conflict-id> --choose <op-oid> --reason "…" # …and pay one: a signed decision
avcs undo --last # take the last operation back out of the view…
avcs checkout # …and re-project the working tree from it
Two things to notice: commit is not a git commit — it authors semantic operations,
the real history; and the working tree is a projection you re-materialize with
checkout, not the source of truth. avcs help lists every command.
Signing identity
An avcs identity belongs to you and this machine, not to one checkout — the same scope as
~/.ssh or ~/.gnupg. Provision it once and every repo on the box can sign with it:
avcs key provision human:you # writes ~/.avcs/private/human:you.json (0600, dir 0700)
avcs key ls # who this machine can sign as, and which keystore each came from
avcs key import <key-file> # put an existing identity on a NEW machine
The keystore is $AVCS_CONFIG_HOME, else $XDG_CONFIG_HOME/avcs, else ~/.avcs. A repo may
keep its own key in <store>/private/ to sign as a different actor (a CI checkout, a second
identity); that override is read first. See 12 — Local production.
Your id is your identity — trust, keys and governance key on it. For attribution and contact, set a display name and email the git way; they ride in every operation you author (so blame and history can show and reach you) but never gate anything:
avcs config user.name "Ada Lovelace"
avcs config user.email "ada@example.com"
avcs config actor "human:ada" # the id commits author as (else your sole key / AVCS_ACTOR)
avcs config # show what is set
These live in .avcs/config.json; AVCS_AUTHOR_NAME / AVCS_AUTHOR_EMAIL / AVCS_ACTOR
override per invocation.
Work against a server
A repo stays useful with no server at all. Once there is one — avcs serve,
avcs-server, or any conforming implementation — the
whole exchange is a handful of commands:
avcs clone https://your.server/acme/web . # fetch the graph AND project a working tree
avcs clone https://your.server/acme/web . --at <checkpoint> # …at one exact checkpoint
avcs sync # pull + push against the remote it recorded
avcs sync --watch # live convergence: long-poll + contention early warning
avcs land -m "add mul()" # push + checkpoint + integrate, in one step
land is the one to reach for. A stale head is absorbed by the server's integration queue
rather than bounced back as "head moved — pull first", so the outcome is landed or a
conflict packet for a human to decide — never a redo. avcs remote add <name> <url>
registers additional servers; avcs sync <name> picks one.
Reading from CI, without handing out a signing key. The default credential is an
AVCS-Sig signature over the canonical request, which covers the method and the body — a
captured read credential cannot be replayed as a write. That is the right default, and a
poor fit for an ephemeral reader. So a read also accepts a bearer token:
AVCS_HUB_TOKEN=… avcs clone https://your.server/acme/web .
The token is read-only by construction: the write path takes no token parameter at all, so a leaked variable can clone but can never push, finalize, or rewrite policy. A held signing key always wins over the token, so a signed reader is never silently downgraded. The token's format, lifetime and scope belong to the server — see docs/26.
Connect agents (MCP)
Agents drive AVCS through its MCP server. Once avcs is installed, register it with the Claude Code CLI:
avcs mcp install # runs `claude mcp add avcs -- avcs mcp` for you (scope: user)
claude mcp list # confirm "avcs" is Connected
avcs mcp itself is the stdio server agents spawn (target repo = $AVCS_REPO, else the cwd). To register by hand — or for any other MCP client — point it at avcs mcp:
claude mcp add avcs -- avcs mcp
The MCP SDK ships as an optionalDependency, so a normal install includes it; no extra step needed.
Every tool answers compactly by default — pretty-printing is an opt-in verbose flag on the
call, because whitespace an agent never reads is still whitespace it pays for.
The loop an agent runs — five moves, and landing is one call:
avcs.guide # the loop, the rules, error recovery
avcs.context.build { intentOid } # provenance, prior decisions, live risks
avcs.operation.propose { path, content } # never write final files directly
avcs.validate.run + avcs.evidence.attach # a behaviour change needs passing evidence
avcs.sync.land { by } # push + checkpoint + integrate → landed | conflict
sync.land is the point: a stale head is absorbed for you, so the outcome is either landed or a conflict packet for a human — never "pull and redo". Add --profile core to advertise only these 13 tools instead of all 39 — the schema an agent is handed drops from 35 KB to 14 KB, on every session:
claude mcp add avcs -- avcs mcp --profile core
To upgrade later, re-run npm install -g @izagood/avcs@latest; to remove it, npm uninstall -g @izagood/avcs (your repo data is left intact).
Install from source
Prefer to track the latest main, or hack on AVCS itself? The bundled install.sh clones the repo and wires up an avcs launcher that points back at the checkout, so updating is just git pull — no reinstall needed.
curl -fsSL https://raw.githubusercontent.com/izagood/avcs/main/install.sh | bash
That one-liner clones the repo to ~/.local/share/avcs (override with --dir/AVCS_HOME) and installs an avcs launcher to ~/.local/bin. Re-running it updates the checkout in place. Already have a clone? Run the installer from inside it instead:
git clone https://github.com/izagood/avcs.git && cd avcs
./install.sh
The launcher lands in ~/.local/bin (override with --bin-dir <dir> or AVCS_BIN_DIR). If ~/.local/bin isn't on your PATH yet, the installer prints the line to add.
Other install-from-source options:
./install.sh --bin-dir /usr/local/bin # system-wide (may need sudo)
./install.sh --name avcs-dev # install under a different command name
./install.sh --dir ~/src/avcs --ref v1 # one-liner mode: clone dir + ref to install
./uninstall.sh # remove the launcher (data is left intact)
If node isn't on your PATH at runtime, point the launcher at one with AVCS_NODE=/path/to/node.
Use as a library (@izagood/avcs)
A hosting server (e.g. avcshub) can depend on the AVCS core as a versioned package. Development and tests run the raw .ts via type stripping, but npm publish ships a tsc-compiled dist/ (JS + type declarations via tsconfig.build.json), so consumers import it with no build tooling of their own.
npm install @izagood/avcs
import { startHub, type HubHandle } from "@izagood/avcs/hub"; // the hub server
import { ObjectStore, CorruptObjectError } from "@izagood/avcs/store";
import { verifyMessage, generateKeypair } from "@izagood/avcs/identity";
import { Repo } from "@izagood/avcs"; // root: primary public API
const hub = await startHub({ repoDir: "./data", port: 8080, gated: true });
Entry points: . (root barrel) · ./hub · ./hub/client · ./store · ./identity · ./types.
Releasing: bump package.json's version in a PR and merge it to main — .github/workflows/release.yml detects the new version, runs npm publish (with provenance), tags the commit vX.Y.Z, and cuts a GitHub Release. The publish steps are guarded by a registry check, so package.json edits that don't change the version are no-ops. Every PR also runs a release dry run (npm run build + npm pack --dry-run) in CI to catch packaging regressions before merge. Requires an NPM_TOKEN repository secret with publish rights to the @izagood scope.
AVCS MCP questions
How do I add AVCS MCP to Claude Code?
Run claude mcp add avcs -- npx -y @izagood/avcs mcp in your terminal. Add --scope user to make it available in every project.
How do I add AVCS MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does AVCS MCP provide?
It exposes 39 tools, including avcs.guide, avcs.governance.status, avcs.approval.record, avcs.context.build, avcs.decision.recall.
How does AVCS differ from Git?
Unlike Git which records snapshots, AVCS stores an operation graph consisting of intent, session, operation, evidence, and decision objects, making merging a deterministic reduction rather than text selection.
Can AI agents use AVCS efficiently?
Yes, AVCS is designed to minimize token usage for agents; for example, landing a change after a PR merge can cost 99% fewer tokens compared to Git.