fabbro

"For you, il miglior fabbro" — after T.S. Eliot, The Waste Land

A local-first code review annotation tool with a terminal UI.

Overview

fabbro lets you annotate code for review using FEM (Fabbro Editing Markup) syntax. It's designed to work with AI coding assistants like Claude Code, enabling structured feedback loops between human reviewers and AI.

Installation

Homebrew (macOS & Linux)

brew tap charly-vibes/charly
brew install fabbro

Scoop (Windows)

scoop bucket add charly https://github.com/charly-vibes/scoop-charly
scoop install fabbro

Go

go install github.com/charly-vibes/fabbro/cmd/fabbro@latest

From Source

git clone https://github.com/charly-vibes/fabbro.git
cd fabbro
go build -o fabbro ./cmd/fabbro

Quick Start

# Initialize fabbro in your project
fabbro init

# Start a review session with content from stdin
cat file.go | fabbro review --stdin

# In the TUI: navigate with j/k, select with v, comment with c, save with w

# Extract annotations as JSON
fabbro apply <session-id> --json

# Or find session by source file (useful for agents)
fabbro apply --file plans/my-plan.md --json

Commands

Command	Description
fabbro init	Initialize fabbro in the current directory (creates .fabbro/)
fabbro review <file>	Start a review session with content from a file
fabbro review --stdin	Start a review session, reading content from stdin
fabbro apply <id>	Show annotations from a session
fabbro apply <id> --json	Output annotations as JSON
fabbro apply --file <path>	Find and apply latest session for a source file
fabbro session list	List all editing sessions
fabbro session show <id>	Show session details and annotation breakdown
fabbro session resume <id>	Resume a previous editing session
fabbro session delete <id>	Delete a session (with confirmation)
fabbro session clean --older-than <duration>	Remove old sessions
fabbro session export <id>	Export session content to stdout or file
fabbro tutor	Start the interactive tutorial (like vimtutor)
fabbro prime	Output AI-optimized workflow context
fabbro completion <shell>	Generate shell completion scripts (bash, zsh, fish, powershell)

See CLI documentation for full details.

TUI Keybindings

Key	Action
j / ↓	Move cursor down
k / ↑	Move cursor up
gg / G	Jump to first/last line
Ctrl+d / Ctrl+u	Scroll half page down/up
/	Search (fuzzy match)
n / p	Next/previous search match
Esc	Clear selection/search
v	Toggle line selection
Space	Open annotation palette (when selected)
c	Comment (when selected)
d	Delete annotation (when selected)
q	Question annotation (when selected)
e	Expand annotation (when selected)
u	Unclear annotation (when selected)
r	Change/replacement annotation (when selected)
w	Save session
Ctrl+C Ctrl+C	Quit (with confirmation)

See TUI documentation for full details.

Shell Completion

Enable tab completion for your shell:

# Bash (add to ~/.bashrc)
source <(fabbro completion bash)

# Zsh (add to ~/.zshrc)
source <(fabbro completion zsh)

# Fish (add to ~/.config/fish/config.fish)
fabbro completion fish | source

FEM Syntax

fabbro uses Fabbro Editing Markup for annotations:

{>> This is a comment <<}

See FEM documentation for the full syntax reference.

Claude Code Integration

fabbro is designed to integrate with Claude Code for AI-assisted code review. See integration guide.

Development

# Run the tool locally (builds and runs in one step)
just run init
just run review --stdin < file.go

# Install to ~/go/bin for testing across directories
just install

# Run tests
just test

# Run full CI pipeline
just ci

# See all available commands
just help

Specifications

All features are defined as Gherkin .feature files in specs/. Each scenario is tagged @implemented, @partial, or @planned to track progress. See the spec coverage matrix for the full breakdown.

Task Tracking

We use beads for issue tracking — a git-native, CLI-first tracker that lives in the repo. Run bd ready to see available work, bd list for all issues.

See CONTRIBUTING.md for the full development workflow.

License

MIT

---

A note on authorship

All the code in this repository was generated by a large language model. This is not a confession, nor an apology. It's a fact, like the one that says water boils at a hundred degrees at sea level: neutral, technical, and with consequences one discovers later.

What the human did is what tends to happen before and after things come into existence: thinking. Reviewing requirements, arguing about edge cases, understanding what needs to be built and why, deciding how the system should behave when reality —which is capricious and does not read documentation— confronts it with situations nobody anticipated. The hours of planning, of design, of reading specifications until exhaustion dissolves the boundary between understanding and hallucination.

The LLM writes. The human knows what it should say.

There is a distinction, even if looking at the commit history makes it hard to find. The distinction is that a machine can produce correct code without understanding anything, the same way a calculator can solve an integral without knowing what time is. Understanding what that integral is for, whether it actually solves the problem, whether the problem was the right problem to begin with — that remains human territory. For now.

Leer en español