gitcell 0.1.0

Local-first, multi-client git companion server: git ops, agent prompt history, and Action-style workflows.
Documentation

gitcell

A self-hosted, multi-client alternative to relying on GitHub's hosted services — a "GitHub replacement" server that runs entirely on infrastructure you control. The backend is a Rust service scaffolded from console-kit.

gitcell is an online service: a single server process can host many repositories and be accessed concurrently by many clients over HTTP.

Pillars

  1. Basic git operations — thin wrappers around the system git CLI (init, status, commit, log), scoped per repository so one server can manage many repos.
  2. Agent prompt history — every prompt/response exchanged with an AI agent is recorded as durable, replayable events via the embedded cellz event-sourced cell engine (one cellz cell per repository), keyed by repository, so you keep a durable, queryable record of how the code changed.
  3. Local Action-style workflows — a minimal, GitHub Actions-like YAML runner that executes workflow steps on the server host (no containerization, no remote cloud runners), reading definitions from <repo>/.gitcell/workflows/*.yml.

Architecture

  • Framework: Rust 2024, Axum 0.8 + Tokio + Tower + Tracing, scaffolded from console-kit's backend starter.
  • Storage: cellz (cellz = { version = "0.2", default-features = false }, embedded, no HTTP stack of its own) for agent prompt/interaction history — each repository maps 1:1 to a cellz cell (an isolated, single-writer SQLite event log under GITCELL_CELLS_DIR), giving gitcell a durable, replayable event log for prompts/responses. Each managed git repository lives under GITCELL_DATA_DIR (default ./data/repos/<repo>) as a plain git working tree.
  • Multi-tenancy: every API route is scoped by a {repo} path segment; repository names are validated (^[A-Za-z0-9_-]+$) to prevent path traversal outside the data directory (this also keeps cellz cell IDs filesystem-safe, since gitcell uses the repository name as the cell ID).
src/
  main.rs      - process entrypoint, wiring config/cellz/router
  lib.rs       - crate root
  config.rs    - environment-driven configuration
  error.rs     - unified error type -> HTTP response mapping
  server.rs    - Axum router and HTTP handlers
  git_ops.rs   - git CLI wrappers, repo path/name validation
  storage.rs   - cellz-backed agent prompt/interaction history
  workflow.rs  - local Action-style workflow discovery & execution
tests/         - integration tests (Axum router via `tower::ServiceExt`)

Configuration

All configuration is via environment variables (with sane local defaults), so the same binary can be deployed for multiple clients/environments without rebuilding:

Variable Default Purpose
GITCELL_HOST 0.0.0.0 Bind address
GITCELL_PORT 8080 Bind port
GITCELL_DATA_DIR ./data/repos Root directory holding managed git repositories
GITCELL_CELLS_DIR ./data/cells Root directory for cellz per-repo event logs (prompt history)
GITCELL_CELLS_STORAGE_DIR ./data/cells-storage Blob storage used by cellz for cell snapshots/backups/leases
GITCELL_CELLS_LEASE_TTL_SECS 60 Single-writer lease TTL for cellz cells

Running

cargo run

API

Working trees live on disk at $GITCELL_DATA_DIR/<repo> (default ./data/repos/<repo>). Edit files there (or from an agent), then use the API for git, prompt history, and workflows.

# Initialize a new repository (creates main + a local git identity)
curl -X POST http://localhost:8080/api/v1/repos/my-repo/init

# List repos, status, diff vs HEAD
curl http://localhost:8080/api/v1/repos
curl http://localhost:8080/api/v1/repos/my-repo/status
curl http://localhost:8080/api/v1/repos/my-repo/diff

# Working tree files (UTF-8). `.git` is blocked.
curl -X PUT http://localhost:8080/api/v1/repos/my-repo/files/src/main.rs \
  -H 'content-type: application/json' \
  -d '{"content": "fn main() {}\n"}'
curl http://localhost:8080/api/v1/repos/my-repo/files/src/main.rs
curl http://localhost:8080/api/v1/repos/my-repo/tree

# Commit (records gitcell.commit, runs on: commit/push workflows)
curl -X POST http://localhost:8080/api/v1/repos/my-repo/commit \
  -H 'content-type: application/json' \
  -d '{"message": "initial commit"}'
curl "http://localhost:8080/api/v1/repos/my-repo/log?limit=5"

# Branches
curl http://localhost:8080/api/v1/repos/my-repo/branches
curl -X POST http://localhost:8080/api/v1/repos/my-repo/branches \
  -H 'content-type: application/json' \
  -d '{"name": "feat-x", "checkout": true}'

# Prompt history is pinned to HEAD by default
curl -X POST http://localhost:8080/api/v1/repos/my-repo/prompts \
  -H 'content-type: application/json' \
  -d '{"role": "user", "content": "please add a login feature"}'
curl "http://localhost:8080/api/v1/repos/my-repo/prompts?commit=HEAD"

# Workflows also still run on demand
curl http://localhost:8080/api/v1/repos/my-repo/workflows
curl -X POST "http://localhost:8080/api/v1/repos/my-repo/workflows/CI/run?event=commit"

Workflow files use a small subset of the GitHub Actions schema, read from <repo>/.gitcell/workflows/*.yml; see examples/workflows/ci.yml for a working example. A successful commit automatically runs workflows that listen for commit or push.

name: CI
on: [commit, push, manual]
env:
  GREETING: "hello from gitcell"
jobs:
  build:
    steps:
      - name: Greet
        run: echo "$GREETING"
      - name: Show shell
        run: uname -a

Development

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test