VCS

AI-native version control, built on git.

VCS is a version control system designed for the age of AI-assisted development. It uses git as the storage backend (like jj) for zero-friction adoption in existing repos, while adding three capabilities that git lacks:

1. Co-located LLM transcripts - Every AI conversation is stored alongside the code it produced, as a first-class VCS object
2. Zoom-level context - Session > Task > Change > Transcript hierarchy lets agents request exactly the context they need
3. Integrated CI - Attestations collapse the commit > push > PR > CI > review loop into a local-first workflow

Features

• Stable Change IDs that survive amends, rebases, and cherry-picks (like jj)
• Colocated mode - runs alongside git, git log always works
• Session & task tracking for AI agent workflows
• Transcript storage with git blob content-addressing
• Attestation system with environment hashing for reproducible CI
• Enriched PR creation with transcripts, attestations, and session context
• Operation log with undo - every mutation is recorded and reversible
• --format=json on every command for agent consumption
• Programmatic API (VcsClient) for direct integration into AI agents

Install

bun install -d @stacksjs/vcs

Or install globally:

bun install -g @stacksjs/vcs

Or compile a standalone binary:

bun build packages/vcs/bin/cli.ts --compile --minify --outfile vcs

Quick Start

# Initialize VCS in an existing git repo
cd my-project
vcs init

# Make changes and commit (no staging area needed)
echo "hello" > hello.txt
vcs commit -m "Add greeting"

# Start an AI session
vcs session:start -m "Implement authentication"
vcs task:create -m "Add JWT middleware"

# Commit with session/task context
vcs commit -m "Add token validation"

# Attach a conversation transcript
vcs transcript:attach conversation.json

# Run attestation (local CI)
vcs attest unit-tests --command "bun test"

# Check CI status
vcs ci:status

# Get context for an AI agent
vcs context --zoom session --format json

# Create an enriched PR
vcs pr:create --title "Add authentication" --base main

Commands

Core Workflow

Sessions & Tasks

Transcripts

CI & Attestation

Context (Agent-Facing)

Git Interop

All commands support --format=json for agent consumption.

Programmatic API

For integrating VCS into AI agents and tools without going through the CLI:

import { VcsClient } from '@stacksjs/vcs'

const vcs = await VcsClient.open('/path/to/repo')

// Start a session
const session = await vcs.sessionStart('Implement auth system', {
  model: 'claude-opus-4-6',
  tool: 'claude-code',
})

// Create a task
const task = await vcs.taskCreate('Add JWT middleware')

// Make changes and commit
await vcs.commit('Add token validation')

// Attach transcript
await vcs.transcriptAttach(
  [
    { role: 'human', content: 'Add JWT middleware to the auth flow' },
    { role: 'assistant', content: 'I\'ll add JWT token validation...' },
  ],
  { model: 'claude-opus-4-6' },
)

// Run attestation
const result = await vcs.attest('unit-tests', 'bun test')
console.log(result.passed) // true/false

// Get context at any zoom level
const ctx = await vcs.context({ zoom: 'session', tokenBudget: 4000 })

// Complete task and session
await vcs.taskComplete()
await vcs.sessionEnd()

Configuration

Create a vcs.config.ts in your project root:

export default {
  verbose: false,

  author: {
    name: 'Your Name',
    email: 'you@example.com',
  },

  ci: {
    checks: [
      { name: 'typecheck', command: 'bun --bun tsc --noEmit' },
      { name: 'lint', command: 'bun run lint' },
      { name: 'test', command: 'bun test' },
    ],
  },
}

Architecture

┌──────────────────────────────────────────────┐
│                 CLI Layer                     │
│  vcs init | commit | log | session | ...     │
├──────────────────────────────────────────────┤
│              Workspace Layer                  │
│  WorkingCopy | Import/Export | Diff           │
├──────────────────────────────────────────────┤
│               Core Layer                      │
│  Types | Config | Errors                      │
├──────────────────────────────────────────────┤
│              Storage Layer                    │
│  GitBackend (isomorphic-git) | MetadataStore │
├──────────────────────────────────────────────┤
│           Git Object Store (.git/)            │
└──────────────────────────────────────────────┘

VCS uses git as the storage backend. All commits are native git commits. VCS metadata lives in .vcs/ (gitignored), custom refs (refs/vcs/), and git notes (refs/notes/vcs/). A plain git log always works.

Data Model

Zoom-level hierarchy:

Session (high-level: "implement auth system")
  └── Task (mid-level: "add JWT middleware")
        └── Change (commit-level: "add token validation")
              └── Transcript (fine-grained: full conversation)

Key concepts:

• Change - The fundamental unit, with a stable ID that survives rewrites. Maps 1:1 to a git commit but can be amended without losing identity.
• Session - An AI working session with an objective, containing tasks and changes.
• Task - A unit of work within a session.
• Transcript - A stored AI conversation with turns, linked to changes.
• Attestation - A CI check result with environment fingerprinting.
• Bookmark - A named pointer to a change, bidirectionally synced with git branches.
• Operation - A recorded mutation for undo support.

Where Things Live

Git Interop

Every VCS commit includes trailers for interoperability:

Fix auth token refresh

Change-Id: kkqrmvlnopstuv
Session-Id: 019479a2-7c8b-...
Task-Id: 019479a3-7c8b-...
VCS-Version: 0.1.0

Users can freely mix git and vcs commands. VCS auto-imports git commits on every command.

Testing

bun test

Development

# Run VCS from source
bun run vcs init

# Run tests
bun test

# Type check
bun run typecheck

# Compile standalone binary
bun run compile

Credits

Inspired by Jarred Sumner's thoughts on what replaces git, and by the design of jj (Jujutsu), Sapling, and Pijul.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Postcardware

"Software that is free, but hopes for a postcard." We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙