# 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
```bash
# 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
```bash
# 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:
```bash
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.