AVCS — Agentic Version Control SystemSAFE
Agentic Version Control System — an AI-native VCS where intent, session, operation, evidence and decision are first-class objects and code is a materialized projection of an operation graph.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
An AI-native version control system for humans and AI agents working concurrently.
[](https://github.com/izagood/avcs/actions/workflows/ci.yml)
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:
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
4298657bf27aOBSERVED · 2026-10-12Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add avcs -- npx -y @izagood/[email protected] mcp
Exposed tools (49)
37 read · 12 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
avcs.approval.record | read | Record a reviewer verdict on a checkpoint, signed with the reviewer |
avcs.blame | read | Who 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.lines | read | Per-line provenance: the op that last wrote each line, with actor, intent and purpose. Why THIS line is here. |
avcs.checkpoint.create | write | Freeze a verified (ops + policy + materializer + evidence) state vector for a view. |
avcs.conflict.list | read | List the conflicts that require a human/owner decision in a view. |
avcs.contention.check | read | Other actors |
avcs.context.build | read | Assemble working context for a scope under a byte budget: provenance, decisions, risks, history. Deterministic truncation. |
avcs.decision.recall | read | Prior human decisions for a conflict key plus the policies they taught. Read precedent before re-deciding. |
avcs.decision.record | read | Record a human owner |
avcs.diff | read | Diff two views/lines. format |
avcs.evidence.attach | read | Attach machine-checkable evidence (test/typecheck/lint/...) to operations. Behavior changes need a passing test to be accepted. |
avcs.governance.status | read | Read-only review state for a view: protection rules, head, your role, and the effective approvals. |
avcs.guide | read | How to use AVCS: the canonical loop, agent rules, tool index, error recovery. Call this first. |
avcs.history | write | History of one entity in causal order. Paged: limit (default 20) + cursor. |
avcs.integration.status | read | Idempotent lookup of an integration ticket |
avcs.integration.submit | write | Submit a checkpoint to the integration queue. Verdict is advanced, conflict, needs_evidence or queued — never |
avcs.intent.create | write | Open an intent: the goal + constraints + allowed scopes for a unit of work. Agents must work within an intent. |
avcs.intent.list | read | List intents in the repo. Bounded: limit (default 50). |
avcs.intent.read | read | Read an intent (goal, constraints, allowed scopes). An agent should read this BEFORE proposing operations so it works within the constraints. |
avcs.key.list | read | Which actors this machine can sign as, and which public keys the repo trusts. Ids only, never key material. |
avcs.key.provision | read | Mint a local signing key for an actor so its decisions and hub writes can be signed. Idempotent. |
avcs.lease.request | write | Request a soft write-lease over entity scopes BEFORE editing, to avoid duplicating another agent |
avcs.line.create | write | Fork a long-lived line (e.g. |
avcs.line.list | read | List the lineage lines in the repo (besides the implicit |
avcs.metrics | read | In-process metrics snapshot for this server (reduce cache hit/miss, reduce.ms timing, materialize.calls). |
avcs.object.show | read | Read an object by oid. Blobs return decoded content (utf8 text or base64); other types return the structured object. |
avcs.onboard | read | Teach the AVCS loop, rules and error recovery — the guide, inlined. |
avcs.operation.backport | read | Cherry-pick an operation onto another line: mints a new op carrying the change, with derivedFrom provenance. Source line untouched. |
avcs.operation.propose | read | Propose a semantic change (MVP: file writes). Declare effects honestly — policy gates on them. baseText/baseBlobOid authors a 3-way-mergeable edit_file. |
avcs.propose-change | read | Draft a change under an intent, with that intent |
avcs.release.cut | read | Cut a release: a conflict-free checkpoint plus evidence, SBOM and artifact references. Refuses if the view has open conflicts. |
avcs.repair.context | read | Minimal repair packet for ops whose validation failed: failing output, related decisions, a fix instruction. Cheaper than re-reading the repo. |
avcs.resolve-repair | read | Repair operations whose validation failed, with the repair packet inlined. |
avcs.review-change | read | Review a checkpoint: changed paths, evidence and the view |
avcs.session.start | write | Begin a work session for an agent/human against an intent. Returns a session id used on every operation. |
avcs.sync.land | write | Land work on a protected head in one call: push, merge-check, checkpoint, integrate. Result is landed or a conflict packet. |
avcs.sync.pull | write | Pull objects from the hub (conflict-free gossip). dryRun reports what would arrive without importing. |
avcs.sync.push | write | Push local objects to the hub. Returns how many were accepted and how many the gate rejected. |
avcs.validate.run | write | Run validation commands against a view and attach treeHash-bound evidence. Pass dir to reuse an existing build environment. |
avcs.view.materialize | read | Reduce a view |
avcs.workspace.land | read | Land a workspace onto its base line: its isolated ops join the base view and merge there. Idempotent. |
avcs.workspace.list | read | List this repo |
avcs.workspace.project | write | Write a view to a directory on disk, so build/test loops outside validate.run need no CLI. |
checkpointOid | read | the checkpoint under review |
guide | read | The canonical loop, agent rules, tool index and error recovery. |
intentOid | read | the intent to work under |
ops | read | comma-separated operation oids |
paths | read | comma-separated paths you expect to touch |
view | read | view name; default main |
Trust audit
SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- none-observed
- Network
- declared (6 observation(s))
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (14)
const url = `http://127.0.0.1:${port}`;await client.saveLocalKey("ai:claude", kp.privateKey); // the local ~/.ssh/id_ed25519 analogueimport { Repo } from "../../src/api/repo.ts";import { computeOid } from "../../src/core/canonical.ts";import type { Actor } from "../../src/objects/types.ts";import { computeOid } from "../../src/core/canonical.ts";import { startHub } from "../../src/hub/hubServer.ts";node --experimental-strip-types $GITHUB_WORKSPACE/src/cli.ts push http://127.0.0.1:8431
AVCS_CONFORMANCE_URL=http://127.0.0.1:8431 npm run conformance
print(f"avcs core server (python, stdlib) on http://127.0.0.1:{args.port}")return { url: `http://127.0.0.1:${port}`, close: () => new Promise<void>((r) => server.close(() => r())) };@modelcontextprotocol/sdk, @types/node, typescript
captured read credential cannot be replayed as a write. That is the right default, and a
curl -fsSL https://raw.githubusercontent.com/izagood/avcs/main/install.sh | bash
Gates applied: no_behavioural_pass.
4298657bf27afull audit observations/trust-audit/mcp-server/izagood__avcs.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-12 | 4298657bf27a | SAFE | B | 89 | first audit |
Questions
What is the @izagood/avcs MCP server?
Agentic Version Control System — an AI-native VCS where intent, session, operation, evidence and decision are first-class objects and code is a materialized projection of an operation graph.
What tools does @izagood/avcs expose?
49 in total: 37 read-only, 12 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is @izagood/avcs safe to connect to an agent?
The audit found nothing in the source that contradicts what it says it does, and graded it B (89/100). Grade A is held back for packages that have also passed a sandboxed behavioural run, which is why a clean server reads B.
What credentials does @izagood/avcs need?
It reads AVCS_AUTHOR, AVCS_AUTHOR_EMAIL, AVCS_AUTHOR_NAME, AVCS_CONFORMANCE_KEYID, AVCS_CONFORMANCE_PRIVATE_KEY, AVCS_CONFORMANCE_PRIVATE_KEY_FILE, AVCS_KEY and AVCS_KEYSTORE_ADOPT from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does @izagood/avcs run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as @izagood/avcs at 0.51.0.
How current is this page?
The grade is for one exact copy of the source (4298657bf27a), read on 2026-10-12. The repository is watched and re-audited when it changes.