onyx/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 push --stacked	Push stacked diffs	N/A (advanced)
onx undo	Undo last operation	git reflog && reset

Push Workflows

Onyx supports two push workflows to match different development styles:

Single-Branch Mode (Default) - Recommended for AI Development

onx push

When to use:

• Default for all standard feature development
• When creating traditional pull requests
• For AI-assisted development sessions
• When you want a clean remote repository UI

What happens:

• Pushes workstream as ONE branch named after the workstream
• Example: milestone-4 branch contains all commits
• Remote UI shows single branch per workstream (clean)
• Perfect for creating GitHub/Gitea pull requests

AI Development Guidance: Use this mode by default. It provides the cleanest integration with standard Git workflows and PR creation tools.

Stacked Diffs Mode (Advanced)

onx push --stacked

When to use:

• Large, complex features requiring incremental review
• When each commit needs independent review/approval
• Meta/Google-style stacked diff workflows
• When explicitly requested by the user

What happens:

• Pushes EACH commit as a separate branch
• Example: onyx/workstreams/milestone-4/commit-1, commit-2, etc.
• Remote UI shows multiple branches (one per commit)
• Each branch can have its own pull request

AI Development Guidance: Only use when specifically requested or when the feature is complex enough to warrant incremental review. The additional branches may clutter the remote UI.

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

IMPORTANT: Dogfooding Policy

This repository uses Onyx for its own development. All development work MUST use Onyx commands exclusively:

• ✅ Use onx save -m "message" to commit changes (NOT git commit)
• ✅ Use onx new <name> to create feature branches (NOT git checkout -b)
• ✅ Use onx switch <name> to switch workstreams (NOT git checkout)
• ✅ Use onx sync to update from remote (NOT git pull)
• ✅ Use onx push to push to remote (NOT git push)
• ✅ Use onx undo to undo operations (NOT git reset)
• ✅ Use onx list to view workstreams (NOT git branch)

Exception: Only use git commands for:

• Initial remote setup (git remote add)
• Creating pull requests via GitHub CLI (gh pr create)
• Inspecting low-level Git state when debugging Onyx itself

This dogfooding validates our user experience and ensures Onyx works correctly for real-world development.

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.