Pick up exactly where you left off.
FlowBack is a developer productivity tool that saves your coding context before a break and brings you back up to speed instantly when you return. It tracks errors across projects, detects recurring patterns, and visualizes skill gaps — all from your terminal.
Before break After break When errors hit
───────────── ──────────── ────────────────
flowback pause flowback resume flowback error "..."
│ │ │
▼ ▼ ▼
Scans recently Shows per-project Root cause + fix
modified files AI briefing: steps. Detects if
across projects goal, stuck point, you're hitting the
next 3 steps, tags same error again
pip install flowbackRequires Python 3.10+. On macOS, if
pipis not found or you see "no matching distribution", use Homebrew Python:python3.11 -m pip install flowback
Then create ~/.flowback/.env with your LLM API key. FlowBack works with any provider via litellm:
Google Gemini (free tier available — recommended)
LLM_MODEL=gemini/gemini-2.5-flash
LLM_API_KEY=your_gemini_key
→ Get a free key at aistudio.google.com
OpenAI
LLM_MODEL=gpt-4o
LLM_API_KEY=your_openai_key
Anthropic Claude
LLM_MODEL=claude-3-5-sonnet-20241022
LLM_API_KEY=your_anthropic_key
Groq (fast + free tier)
LLM_MODEL=groq/llama-3.1-70b-versatile
LLM_API_KEY=your_groq_key
Ollama (fully local — no API key needed)
LLM_MODEL=ollama/llama3
LLM_API_BASE=http://localhost:11434
That's it. No server to run. Works from any terminal.
flowback pause ~/projects/myapp
flowback pause ~/projects/myapp ~/projects/other # multiple projects at once
flowback pause ~/projects/myapp --note "debugging auth middleware, getting 401s"flowback resume # latest session
flowback resume --all # all past sessionsEach project gets its own AI briefing:
─────────────── Session #18 2026-03-15 11:49 ───────────────
╭─ fashio-ai — Goal ──────────────────────────────────────────╮
│ Building AI-powered fashion virtual try-on with image │
│ processing and Supabase storage integration. │
╰─────────────────────────────────────────────────────────────╯
╭─ Stuck point ───────────────────────────────────────────────╮
│ Client-side cropped images not returning public URLs │
│ from Supabase for AI service consumption. │
╰─────────────────────────────────────────────────────────────╯
╭─ Next steps ────────────────────────────────────────────────╮
│ 1. Debug ensurePublicUrl in src/lib/ai-service.ts │
│ 2. Add error logging to upload pipeline │
│ 3. Test with small static images first │
╰─────────────────────────────────────────────────────────────╯
#file-upload #supabase-storage #api-integration
# Paste an error directly
flowback error "TypeError: Cannot read properties of undefined"
# Pipe from any command
npm run build 2>&1 | flowback error
python manage.py migrate 2>&1 | flowback error
# See all tracked errors with occurrence counts
flowback errors| Occurrences | Response |
|---|---|
| 1st time | Root cause + 3 fix steps + prevention tip |
| 2nd time | ⚠ "Seen twice — watch this pattern" |
| 3rd+ time | 🔁 "You're in a loop!" + tailored break-the-loop advice |
flowback graphGenerates a self-contained HTML file and opens it in your browser — no server needed. Shows a force-directed graph of your errors, the projects they appeared in, and the skill areas they involve.
graph TD
classDef error fill:#ef4444,color:#fff,stroke:#dc2626
classDef project fill:#3b82f6,color:#fff,stroke:#2563eb
classDef tag fill:#a855f7,color:#fff,stroke:#9333ea
E1("TypeError ×4"):::error --- P1("fashio-ai"):::project
E1 --- P2("flowBack"):::project
E1 --- T1("#null-check"):::tag
E2("401 Unauthorized ×3"):::error --- P1
E2 --- T2("#auth-token"):::tag
E3("CORS Error ×2"):::error --- P2
E3 --- T2
E3 --- T3("#api-integration"):::tag
E4("ModuleNotFoundError ×1"):::error --- P2
E4 --- T4("#dependency"):::tag
| Node | Color | Meaning |
|---|---|---|
| Error | 🔴 Red | A unique error type — size = how many times you've hit it |
| Project | 🔵 Blue | A project where errors occurred |
| Skill tag | 🟣 Purple | A skill area extracted from errors — size = how often it's involved |
- Large red node → recurring error, fix it properly
- Red node linked to multiple blue nodes → cross-cutting knowledge gap, not project-specific
- Large purple node → skill area to study
flowback tagsConnect FlowBack directly to Claude Code. Your context, errors, and skill gaps become Claude tools — available through natural language, no commands needed.
# Register with Claude Code (one time, after installing)
claude mcp add flowback flowback-mcp| Tool | What it does |
|---|---|
resume |
Returns your last briefing so Claude has full context at session start |
pause |
Scans project folders and saves context |
track_error |
Analyzes an error, returns root cause + fix, detects loops |
skill_gaps |
Returns recurring patterns and skill areas to strengthen |
"Resume my context from yesterday"
"I'm getting this error — track it and tell me the fix: [paste error]"
"What skill gaps am I building up?"
"Save my context for ~/projects/myapp before I take a break"
Claude calls the right tool automatically and returns the analysis inline.
A React/Vite browser interface is included for those who prefer a visual workflow. Requires both servers running.
# Terminal 1 — API server
cd backend
pip install -r requirements.txt
uvicorn main:app --reload # http://localhost:8000
# Terminal 2 — frontend
cd frontend
npm install
npm run dev # http://localhost:5173Three tabs: Pause · Resume · Graph
FlowBack/
├── flowback/
│ ├── cli.py # CLI commands
│ ├── mcp_server.py # Claude Code MCP tools
│ ├── capture.py # file scanner
│ ├── database.py # SQLite (~/.flowback/history.db)
│ ├── llm.py # multi-provider LLM integration (litellm)
│ └── models.py # Pydantic models
├── backend/
│ └── main.py # FastAPI server (web UI only)
├── frontend/ # React/Vite web UI (optional)
└── pyproject.toml
| Layer | Technology |
|---|---|
| AI | Any provider via litellm (Gemini, OpenAI, Claude, Groq, Ollama…) |
| CLI | Python, Typer, Rich |
| Graph | force-graph.js (self-contained HTML) |
| Storage | SQLite (~/.flowback/history.db) |
| MCP | Anthropic MCP SDK |
| Web UI (optional) | FastAPI, React 18, Vite, Tailwind CSS |
- All data stays local — the only thing that leaves your machine is file snippets sent to your configured LLM. With Ollama, nothing leaves your machine at all.
- Scans up to 5 recently modified files per folder within the last 2 hours, skipping binaries,
node_modules,.git, and build output. - History is stored at
~/.flowback/history.db— shared between the CLI, MCP server, and web UI. - The Choose folder button in the web UI is macOS-only (
osascript). On other platforms type the path manually.