ledger AGENTS.md

AGENTS.md

This file helps AI assistants understand and work with the Ledger codebase.

Project Overview

Ledger is a macOS desktop app for viewing git branches, worktrees, and pull requests. Built with Electron + React + TypeScript.

Quick Facts

Aspect	Details
Type	Electron desktop app
Platform	macOS (Apple Silicon)
Language	TypeScript (strict mode)
UI	React 19 + custom CSS
Git	simple-git library
PRs	GitHub CLI (gh)
Tests	Playwright E2E
Build	electron-vite + electron-builder

Key Files to Know

lib/main/main.ts         # IPC handlers, app lifecycle
lib/services/            # Git operations as pure functions (branch, commit, stash, etc.)
lib/services/codegraph/  # Code dependency graph parsing (PHP, Ruby, TypeScript)
lib/conveyor/            # Typed IPC with Zod validation (schemas, handlers, APIs)
lib/preload/preload.ts   # API exposed to renderer
app/app.tsx              # Main React component (large)
app/styles/app.css       # All styling (large)
app/types/electron.d.ts  # TypeScript types for IPC
app/components/          # UI components (panels, canvas, window)
resources/scripts/       # External parser scripts (PHP, Ruby)

Common Tasks

Adding a new git operation

1. Add pure function to appropriate service in lib/services/ (e.g., branch-service.ts)
2. Add Zod schema in lib/conveyor/schemas/
3. Add handler in lib/conveyor/handlers/
4. Add API method in lib/conveyor/api/
5. Call via window.conveyor.* from renderer

Adding UI elements

Main UI is in app/app.tsx. Components are in app/components/:

• panels/editor/ - Editor panels (BranchDetail, PRReview, Staging, etc.)
• panels/viz/ - Visualization panels (GitGraph, ERD, CodeGraph)
• panels/viz/codegraph/ - Code dependency graph visualization
• canvas/ - Canvas layout system
• window/ - Window chrome (Titlebar, menus)

Styling in app/styles/app.css uses CSS variables for theming.