⚠️ Beta Software — Owl is in early development and not yet ready for production use. APIs, configuration, and UI are subject to change without notice.

A visual diff viewer for local Git worktrees. Owl renders unified diffs with syntax highlighting, a file tree sidebar, and line-link selection. It runs entirely against your local repository — no pull requests, no URLs, just your working copy.

• Features
• Stack
• Getting Started
  • Prerequisites
  • Installation
  • Running the Dev Server
• Configuration
• API
• Scripts
• Project Structure
• Architecture
• Contributing
• License

• Worktree diff — View all local changes (staged, unstaged, and untracked files) in one unified patch.
• Syntax highlighting — Code is highlighted using the @pierre/diffs engine with streaming web worker support.
• File tree sidebar — Browse changed files by path with Git status indicators (added, modified, deleted, untracked).
• Line-link selection — Select and link to specific lines in the diff for sharing and navigation.
• Dark theme — Built-in dark theme with Geist font.
• Fully local — No network calls to external Git forges. All operations target your local repository.

• Bun 1.3 or later
• Git 2.30 or later
• A local Git repository (worktree) to inspect

git clone git@github.com:crnvl96/owl.git && cd owl
bun install

export OWL_WORKTREE_PATH=/absolute/path/to/your/git/repo   # optional; defaults to current directory
bun dev

Open http://localhost:5173 in your browser to view the app.

• Vite dev server runs on port 5173 and serves the React frontend with HMR.
• Hono API server runs on port 3000. In development, Vite proxies /api requests to it automatically.

The target directory must be a valid Git working tree.

All configuration is server-side via environment variables. There is no .env file or runtime config UI at this stage.

The Hono server exposes a single API endpoint:

Response

• 200 — Raw unified diff text (text/plain).
• 422 — No local changes (body: "No local changes in the current worktree.").
• 500 — Git command failed (body contains the error message).

The response includes the headers:

• X-Patch-Source: local-worktree
• Cache-Control: no-store

Run bun check before committing. It ensures formatting, linting, and type checking all pass.

owl/
├── public/                  # Static assets (fonts, etc.)
├── src/
│   ├── frontend/            # React client
│   │   ├── components/
│   │   │   ├── atoms/       # Primitives (Button, Toaster)
│   │   │   ├── diff/        # Diff rendering components
│   │   │   ├── layout/      # Layout, worker pool, preloading
│   │   │   └── review/      # Review UI (file tree, sidebar, viewer)
│   │   ├── hooks/           # React hooks (theme, worker pool, patch loader)
│   │   ├── lib/             # Client-side utilities (config, caching, streaming, types, theme)
│   │   ├── pages/           # Page components (Home)
│   │   ├── globals.css      # Global styles
│   │   └── main.tsx         # Entry point
│   └── server/              # Hono API server
│       ├── git.ts           # Git command runner and worktree resolution
│       └── index.ts         # Server entry point (API routes + static serving)
├── types/                   # Ambient type declarations
├── index.html               # HTML shell
├── vite.config.ts           # Vite configuration
├── tsconfig.json            # TypeScript configuration
├── components.json          # shadcn/ui configuration (for reference)
├── package.json             # Dependencies and scripts
└── bun.lock                 # Bun lockfile

• Frontend is a single-page React application bootstrapped in src/frontend/main.tsx. It communicates exclusively with the Hono API server at /api.
• Server is a thin Hono app that spawns git child processes to generate diffs. All Git operations are server-side only and scoped to the worktree configured via OWL_WORKTREE_PATH.
• Diff rendering uses @pierre/diffs for parsing and rendering unified diffs (the only view mode currently supported), with syntax highlighting offloaded to web workers for responsiveness on large patches.
• File tree is powered by @pierre/trees, which builds a hierarchical file listing from the diff output and annotates each entry with its Git change type.

1. Fork the repository.
2. Create a feature branch: git checkout -b feat/my-feature
3. Make your changes.
4. Run bun check to ensure formatting, linting, and types are clean.
5. Commit and push your branch.
6. Open a pull request.

Please keep changes focused and avoid large, unrelated refactors in feature PRs.

This project has not yet adopted a license. All rights are reserved by the author(s) until one is chosen.