fbl-ai

fbl

Automated session analysis for Claude Code — detect frictions, suggest improvements, close the feedback loop.

What it does

Every time you close a Claude Code session, fbl analyzes the transcript, detects recurring frictions, and suggests actionable rules to add to your CLAUDE.md. It learns from your mistakes so you don't repeat them.

Privacy-first: Your code and transcripts never leave your machine. Only anonymized friction patterns are shared (opt-in).

Model-agnostic: Works with Anthropic (Haiku/Sonnet), OpenRouter (100+ models), or fully local via Ollama.

Quick Start

npm i -g fbl-ai                # Install globally
fbl init                       # Configure provider + install hook
fbl analyze --last 7d          # Analyze past sessions (instant value)
fbl report                     # See frictions + suggestions
fbl apply 1                    # Apply suggestion #1 to CLAUDE.md

How it works

Claude Code session ends
        │
        ▼
SessionEnd hook triggers (async, < 100ms)
        │
        ▼
Background worker reads transcript JSONL
        │
        ▼
LLM analyzes for frictions & suggestions
        │
        ▼
Results stored locally (~/.fbl/)
        │
        ▼
`fbl report` shows insights
        │
        ▼
`fbl apply` edits CLAUDE.md via Claude Code headless

Features

• Automatic analysis — hook runs after every session, zero effort
• Friction detection — identifies wrong approaches, buggy code, scope bloat, missing context, and more
• Actionable suggestions — specific rules for CLAUDE.md, skills, workflows, and hooks
• Historical analysis — analyze --last 30d to get value from day one
• Cost estimation — see estimated cost before analyzing historical sessions
• Apply with one command — apply <n> uses Claude Code headless to edit CLAUDE.md intelligently
• Community insights — anonymous telemetry powers global recommendations (opt-in)
• 3 LLM providers — Anthropic, OpenRouter, or local (Ollama)

Commands

Command	Description
fbl init	Interactive setup wizard
fbl analyze --last <duration>	Analyze past sessions
fbl report [--last <duration>]	Show friction report + suggestions
fbl apply <n>	Apply suggestion using Claude Code
fbl history [--last <duration>]	Timeline of past analyses
fbl config [--show|--provider|--telemetry]	View/update configuration
fbl gain	Show token savings analytics

Configuration

Config is stored in ~/.fbl/config.json. Use fbl config to modify.

Providers

Provider	Pros	Cons	Default model
Anthropic	Fast, accurate	API key needed	claude-haiku-4-5
OpenRouter	100+ models, cheap	API key needed	llama-3.1-8b
Local (Ollama)	Free, private	Slower, less accurate	llama3.1:8b

Telemetry

When opted-in, fbl sends anonymized friction patterns (types, categories, severity counts) to improve community recommendations. Never sent: code, transcripts, file paths, descriptions, or rules.

Disable anytime: fbl config --telemetry off

Privacy

What stays local	What's shared (opt-in only)
Source code	Friction types & categories
Transcripts	Severity counts
File paths	Suggestion targets
Descriptions & rules	Satisfaction signals
CLAUDE.md content	Hashed device ID

Requirements

• Node.js >= 22
• Claude Code installed
• An LLM provider (Anthropic API key, OpenRouter key, or Ollama running locally)

License

FSL-1.1-MIT — Free to use, will become MIT on 2028-03-22.

Contributing

Contributions welcome! Please open an issue first to discuss changes.