onyx-prebootstrap/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Onyx is a next-generation version control system designed as a superior user experience layer on top of Git. It provides transparent versioning, workstreams for stacked-diff management, and an action log for universal undo functionality. The project is written in Go and uses the go-git library for Git interaction.

Development Commands

Building

# Build the CLI and daemon
go build -o bin/onx ./cmd/onx
go build -o bin/onxd ./cmd/onxd

# Install to PATH
go install ./cmd/onx
go install ./cmd/onxd

Testing

# Run all tests
go test -v ./...

# Run tests with coverage
go test -cover ./...

# Run specific test package
go test -v ./internal/core

Development Setup

This is a Go 1.24.2 project. Initialize dependencies with:

go mod tidy

Key dependencies:

• github.com/go-git/go-git/v5 - Git interaction
• github.com/spf13/cobra - CLI framework (planned)
• github.com/fsnotify/fsnotify - Filesystem monitoring (planned)

Architecture

Core Design Principles

• 100% Git Data Model Compatibility: Uses standard .git directory for shared truth
• Hybrid Storage: .git for Git objects, .onx for Onyx-specific metadata
• Transparent Versioning: Background daemon creates continuous snapshots
• Workstreams: Stacked-diff workflow management
• Action Log: Transactional undo/redo capability

Project Structure (Planned)

onyx/
├── cmd/
│   ├── onx/           # CLI entry point
│   └── onxd/          # Daemon entry point
├── internal/
│   ├── core/          # Core abstractions
│   ├── git/           # Git interaction layer
│   ├── models/        # Data models
│   ├── storage/       # .onx directory management
│   ├── commands/      # CLI command implementations
│   ├── daemon/        # Daemon implementation
│   └── utils/         # Utilities
├── pkg/               # Public APIs
├── test/              # Integration tests
└── docs/              # Documentation

Key Components

1. Repository (internal/core/repository.go)

Central object encapsulating access to both Git repository (via go-git) and Onyx metadata.

2. Action Log (internal/storage/oplog.go)

Append-only binary log storing state before/after each operation for undo functionality.

3. Workstreams (internal/storage/workstreams.go)

Manages stacked-diff workflows through .onx/workstreams.json.

4. Daemon (internal/daemon/)

Background process using fsnotify for continuous snapshot creation.

.onx Directory Structure

.onx/
├── oplog              # Append-only binary action log
├── workstreams.json   # Workstream definitions
├── workspace          # Pointer to current ephemeral commit
├── rerere_cache/      # Git rerere conflict resolution cache
└── index.db          # SQLite index (future feature)

Core Commands (Phase 1)

Command	Purpose	Git Equivalent
onx init	Initialize repository	git init
onx new <name>	Create workstream	git checkout -b
onx save -m "msg"	Save work	git add && git commit
onx list	List workstreams	git branch
onx switch <name>	Switch workstreams	git checkout
onx sync	Update with remote	git pull --rebase
onx push	Push workstream	git push
onx undo	Undo last operation	git reflog && reset

Implementation Status

This is currently a planning/prototype phase. The codebase contains:

• Go module setup
• Comprehensive architectural documentation in notes/
• Detailed implementation roadmap
• Technical specifications for core components

Development Guidelines

Code Style

• Follow Go conventions and idioms
• Use structured logging (planned: zap or logrus)
• Implement proper error handling with custom error types

Testing Strategy

• Unit tests for each component (target: 80% coverage)
• Integration tests for full workflows
• Benchmark tests for performance-critical paths

Git Integration

• All repository data must remain compatible with standard Git clients
• Onyx operations should be reversible via standard Git commands
• Never break the underlying Git object model

Key Algorithms

Transparent Versioning

1. Daemon monitors filesystem with fsnotify
2. On changes (debounced 500ms), create Git tree snapshot
3. Create ephemeral commit with auto-generated message
4. Update refs/onyx/workspaces/current pointer

Workstream Sync

1. Fetch latest from origin base branch
2. Sequentially rebase each commit in workstream stack
3. Use rerere for automated conflict resolution
4. Update all branch refs atomically

Action Log Transaction

1. Capture state_before (all managed refs)
2. Execute command logic
3. Capture state_after
4. Write entry to oplog with both states

This architecture enables sophisticated workflows while maintaining full Git compatibility.