From 7ef57642cc96f4bb28dbdcd52cec271e7c1c5573 Mon Sep 17 00:00:00 2001
From: Tanishq Dubey <dubey@dws.rip>
Date: Thu, 9 Oct 2025 18:41:16 -0400
Subject: [PATCH] Add claude docs

---
 CLAUDE.md | 155 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 155 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..1ad5fa7
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,155 @@
+# 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.
\ No newline at end of file