From b6148b9fd878e93263c8a5fcbe36ddff13b287f4 Mon Sep 17 00:00:00 2001
From: Kaj Kowalski <info@kajkowalski.nl>
Date: Thu, 18 Dec 2025 07:53:50 +0100
Subject: [PATCH] Add CLAUDE.md for Claude Code guidance

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

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..8439481
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,63 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a custom status line binary for Claude Code, written in Go. It replaces shell-based status line scripts with a compiled binary for better performance. The binary reads JSON from stdin (provided by Claude Code) and outputs a formatted status line with ANSI colors.
+
+## Build and Development Commands
+
+This project uses [Task](https://taskfile.dev) as its build tool.
+
+```bash
+# Build (default)
+task build           # Build with stripped symbols to bin/statusline
+
+# Testing
+task test            # Run unit tests (go test -v ./...)
+task test:cover      # Run tests with coverage
+task test:fixture    # Test with fixture JSON and show timing
+
+# Linting
+task lint            # Run golangci-lint
+task lint:fix        # Run golangci-lint with auto-fix
+
+# Other
+task run             # Build and run with test fixture
+task tidy            # Run go mod tidy
+task install         # Install binary to ~/.claude/
+task size            # Show binary size
+task clean           # Remove bin/ directory
+```
+
+## Architecture
+
+Single-file Go application (`main.go`) that:
+
+1. **Reads JSON from stdin** - Parses Claude Code's status hook payload (`StatusInput` struct)
+2. **Gathers system state**:
+   - Gitea process status via gopsutil (cross-platform process listing)
+   - Git repository info via go-git (branch name, dirty state)
+   - Terminal width via unix ioctl
+3. **Outputs formatted status line** with ANSI colors, padding to terminal width
+
+Key functions:
+- `formatContextInfo()` - Formats token usage as "Xk/Yk"
+- `getGiteaStatus()` - Returns green/red dot based on gitea process running
+- `getGitInfo()` - Returns git branch and dirty indicator
+- `stripANSI()` - Removes ANSI codes for visible length calculation
+
+## JSON Input Format
+
+The binary expects Claude Code's status hook JSON via stdin. See `test/fixture.json` for the complete structure. Key fields used:
+- `model.display_name` - Model name to display
+- `workspace.current_dir` - Current directory path
+- `context_window.context_window_size` - Total context window tokens
+- `context_window.current_usage` - Current token usage (may be null)
+
+## Dependencies
+
+- `github.com/go-git/go-git/v6` - Pure Go git implementation
+- `github.com/shirou/gopsutil/v4` - Cross-platform process/system info
+- `golang.org/x/sys` - Unix system calls (terminal size)