@chr33s/git

Git Smart-HTTP server, browser client, and Unix CLI built from one core
Built on Effect v4 with modern TypeScript and Web APIs.

One Git core runs in a Cloudflare Durable Object, on plain Node.js, in a browser tab, and directly as a Unix CLI. Standard Git clients clone from it, push to it, and read the index and history generated by its commands.

• The whole project fetches: Source code, developer identities, key logs, pull requests, code reviews, and automated checks live inside native Git objects and refs. A single git fetch provides complete, causally-ordered state without relying on hosting provider web APIs.
• The forge runs in the sandbox: One core engine serves requests across Durable Objects, local Node processes, browser tabs, and terminal environments. Ephemeral agent containers can host, review, and merge code locally without third-party API rate limits.
• Capability-scoped authority: Permissions are bound to explicit capabilities (source.push, hub.check:test). Short-lived tokens are minted via member SSH keys without relying on centralized token registries.
• Cryptographic authorship: Every code review, attestation, and trust change is SSH-signed and tied to exact head commit SHAs. Self-approvals are rejected at the protocol level.
• Built for concurrent agent workflows: PR collaboration is represented as an append-only event DAG converging by DAG union. Merge policies apply via atomic compare-and-swap (CAS) operations at the ref boundary.
• Containable errors: Retroactively revoke compromised keys to invalidate past events, or issue replicating tombstone events to scrub leaked secrets without breaking hash chains.

The same repository domain service sits behind each surface. Storage is supplied by platform-specific ports; Git object formats, merge behavior, and protocol rules stay in the shared core.

                    ┌───────────────────────┐
                    │      Repository       │
                    │ shared Git domain core│
                    └───────────┬───────────┘
        ┌───────────────────────┼───────────────────────┐
        │                       │                       │
   Smart-HTTP / JSON API    Unix CLI              Browser client
        │                       │                       │
   Node / Cloudflare       filesystem ports          OPFS ports

The server surfaces speak Git Smart-HTTP and the JSON API through the same Repository operations. The CLI adds working-tree and index ports. Browser storage uses OPFS while keeping the same Git object model. Contributor-level module boundaries, storage contracts, and testing rules are documented in docs/internals.md.

Choose the document for the job rather than reading the design set front to back:

This repository is currently not published to npm (package.json is private). Install mise and use the checkout instead. Node 26 is the blessed development and binary-build version; the source compatibility floor is Node 24.12.0.

git clone https://github.com/chr33s/git.git
cd git
mise install
npm ci                 # installation does not rewrite the checkout

Both server implementations speak standard Smart-HTTP (v0/v2), Git LFS, and export a type-safe JSON API.

# Explicit flags take precedence over environment variables.
git+ serve --root ./repos --port 8080

# The same shared configuration works for the CLI and standalone Node host.
GIT_ROOT=./repos git+ serve

# Serve with write access enabled for un-guarded repositories.
git+ serve --root ./repos --open

Standard Git clients can interact directly with the server:

git clone http://127.0.0.1:8080/my-repo.git

The CLI wraps the unified core repository engine. Its command tree is the canonical reference:

git+ --help
git+ <command> --help

docs/cli.md is generated from that command tree and is the checked-in top-level help snapshot. Use it for the exact command inventory; this README intentionally does not duplicate that list.

The CLI covers repository creation and transport, working-tree commands, history and search, refs and rewriting, hub and social operations, pull requests and queues, agent sessions and tasks, server administration, and maintenance. If a command changes, update the command tree and regenerate docs/cli.md with npm run docs:cli rather than maintaining a second list here.

The hub extension (docs/hub.md) brings repository identity, membership, pull requests, reviews, checks, tasks, and agent provenance into Git refs.

refs/
├── meta/
│   ├── trust/
│   │   ├── genesis             # Repository identity and root authority
│   │   └── log                 # Grants and revocations
│   └── policy                  # Branch and hub policy
└── hub/
    ├── pr/                     # Pull-request event DAGs
    ├── task/                   # Agent task assignments and resolutions
    ├── session/                # Agent-session provenance
    └── queue/                  # Merge-queue coordination

• Task Coordination (git+ task): Fleets organize directly inside the repository. Tasks record requirements, assigned agents, and resolutions as signed events appended to refs/hub/task/. Tasks self-release upon lease expiration if an agent drops offline.
• Session Tracking (git+ session): Records prompt history, agent actions, and outcome states.
• Automated Wake Triggers (git+ wake): Runs repository-defined execution rules whenever a push updates hub references.

# Claim a pending task from the hub DAG
git+ task claim --id="task-102" --ttl="15m"

# Execute task work, post status attestation, and release claim
git+ task resolve --id="task-102" --status="completed"

The web interface in src/ui/ provides a lightweight file browser, commit viewer, task manager, and pull request inspector powered by Lit and Web Components.

# Development mode: watch UI and bind embedded API server on :8000
GIT_ROOT=./repos npm run dev:ui

# Build production bundle and serve statically
npm run build:ui
git+ serve --root ./repos --ui

# Install workspace dependencies without changing source files
npm ci

# Read-only formatting, lint and type checks
npm run check

# Fast feedback loop
npm run test:unit

# Integration suite only (workerd)
npm run test:integration

# Pinned stock-Git and SEA compatibility suite
npm run test:interop

# Everything
npm test

# Build the preferred end-user executable (Node 26+)
npm run build:sea
./dist/sea/git+ --help

Use the raw TypeScript entry (node src/cli/main.ts) for contributor work; the SEA binary is the supported end-user distribution while npm publishing is off.

npm run check intentionally includes the repository's Effect and anti-slop rules as correctness checks, not automatic style fixes. npm run fix is the explicit opt-in formatter/linter repair command. Run npm run setup only to regenerate build metadata and Wrangler binding types (for example, after changing package.json or wrangler.test.json); it is never part of installation or checking.