███████╗██╗      █████╗ ███████╗██╗  ██╗██████╗  █████╗  ██████╗██╗  ██╗███████╗██████╗ 
██╔════╝██║     ██╔══██╗██╔════╝██║  ██║██╔══██╗██╔══██╗██╔════╝██║ ██╔╝██╔════╝██╔══██╗
█████╗  ██║     ███████║███████╗███████║██████╔╝███████║██║     █████╔╝ █████╗  ██████╔╝
██╔══╝  ██║     ██╔══██║╚════██║██╔══██║██╔══██╗██╔══██║██║     ██╔═██╗ ██╔══╝  ██╔══██╗
██║     ███████╗██║  ██║███████║██║  ██║██████╔╝██║  ██║╚██████╗██║  ██╗███████╗██║  ██║
╚═╝     ╚══════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═════╝ ╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝
                                                                                          
         ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
       ░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░
     ░░▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒░░
   ░░▒▒▓▓██████████████████████████████████████████████████████████████████▓▓▒▒░░
 ░░▒▒▓▓████  M E M O R I E S   F L O A T I N G   B A C K   I N   T I M E  ████▓▓▒▒░░
   ░░▒▒▓▓██████████████████████████████████████████████████████████████████▓▓▒▒░░
     ░░▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒░░
       ░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░
         ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

Claude Code state management with session continuity and AI personas

Flashbacker provides:

Session continuity for Claude Code through intelligent state management memory commands
Specialized AI personas accessed via /fb: slash commands
Dedicated agents accessed via @agent-{AGENT-NAME} commands
Agent discussion system for complex issues
A code task management system for complex issues
A code quality and fix system for complex issues

Current Status: v2.4.1 - 🚧 ALPHA - Complete workflow system with 20 total specialists. PM2 daemon foundation with per-project ecosystem generation and CLI management. Status line: robust model detection, stateful output, JSONL fallback, session-aware cache, and repository-root state persistence. Restored /fb:create-issue command for comprehensive issue documentation.

🚀 Quick Start

Prerequisites

Node.js: 18.x, 20.x, or 22.x LTS (recommended: 22.x)
npm: 9.x or later

Quick Prerequisites Installation

# Option 1: Use our automated installer script
npm run setup:prereqs

# Option 2: Manual nvm installation (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install 22
nvm use 22

# Option 3: Download from https://nodejs.org/ (LTS version)

Quick Installation

Option 1: NPM Package (RECOMMENDED)

# Install globally from npm registry
npm install -g flashbacker

# Initialize in your project with MCP servers
cd /path/to/your/project
flashback init --mcp              # Includes context7, playwright, sequential-thinking

Option 2: Automated Installer Script

# Alternative: Single command installation with automatic template refresh
curl -fsSL https://raw.githubusercontent.com/agentsea/flashbacker/main/scripts/install.sh | bash

# Then initialize in your project
cd /path/to/your/project
flashback init --mcp              # Includes context7, playwright, sequential-thinking

Option 3: Manual Source Installation

# For development or latest unreleased features
git clone https://github.com/agentsea/flashbacker.git
cd flashbacker
npm install && npm run build && npm link

# Initialize with MCP servers (RECOMMENDED)
cd /path/to/your/project
flashback init --mcp              # Includes context7, playwright, sequential-thinking

📖 Complete Installation Guide →
📚 User Guide →
Comprehensive command guide with workflows and how-to's

🎯 How You Actually Use Flashbacker

After installation, you use Flashbacker through slash commands in Claude Code:

Primary Commands (What You'll Use Daily)

# Persona Commands (Current Conversation) - Specialized templates applied to current conversation
/fb:persona architect "review our API design"     # Systems architecture analysis
/fb:persona security "analyze authentication"     # Security expert analysis
/fb:persona database-architect "optimize schema" # Database design patterns
/fb:persona john-carmack "optimize hot path"      # Performance-critical systems

# Agent Commands (Dedicated Subagents) - Launch dedicated subagent with full context
@agent-architect "comprehensive API analysis"     # Spawns subagent with project context
@agent-security "security audit with remediation" # Project-aware security analysis
@agent-code-critic "brutally honest code review"  # Code quality enforcement
@agent-john-carmack "performance analysis"        # Game engine principles approach

# Session Management - Manual memory management (NO automatic hooks)
/fb:working-plan {context}                        # Update development priorities
/fb:save-session                                  # Capture session insights before compaction
/fb:session-start                                 # Restore context after compaction
/fb:remember {key insight}                        # Save important info to memory
/fb:how "explain what you understood"              # Get implementation plan

# Code Quality & Task Management
/fb:debt-hunter                                   # Hunt technical debt with AST analysis
/fb:hallucination-hunter                          # Hunt fake AI-generated code
/fb:fix-master "error description"                # Surgical fix methodology
/fb:create-issue "issue-title" priority effort     # Generate comprehensive issue documentation
/fb:create-tasks "issue description"               # Break down issues into atomic tasks
/fb:work-task {task-number}                       # Focus on specific task
/fb:update-tasks {task-number}                    # Update task progress

# Discussion System - Multi-agent collaboration (READ ONLY recommended)
flashback discuss "Should we use microservices?" john-carmack,architect,security
/fb:discuss architect,security "review this code" # In-conversation multi-agent review

What Happens Behind the Scenes

Persona Commands (/fb:persona architect "review API"):

Direct template application: Reads persona template from .claude/flashback/personas/architect.md
Simple output: Template content + your request in current conversation
Immediate analysis: No subagent spawn, direct analysis

Agent Commands (@agent-architect "review API"):

Agent spawning: Claude Code spawns dedicated architect subagent
Context gathering: Agent runs flashback agent --context to get project bundle
Rich context: Agent receives REMEMBER.md, WORKING_PLAN.md, conversation history
Project-aware analysis: Specialized analysis with full project understanding

Session Management (Manual - No Automatic Hooks):

When context window hits ~10%, run /fb:save-session or /fb:working-plan
After compaction, run /fb:session-start to restore context
Memory files: REMEMBER.md, WORKING_PLAN.md, CURRENT_SESSION.md

✨ Core Features

🧠 Session Continuity System (Manual)

Manual Memory Management: Claude Code lacks pre/post-compaction hooks
Memory Injection: REMEMBER.md prevents repeated corrections across sessions
Working Plan Intelligence: AI analyzes conversations to update development plans
Session Restoration: /fb:session-start restores context after compaction

🎭 Dual-Layer AI System

Layer 1: Personas (Current Conversation)

/fb:persona architect "analyze API design" - Direct template application
All 20 personas available for immediate analysis in current conversation

Layer 2: Agents (Dedicated Subagents)

@agent-architect "analyze API design" - Spawns dedicated subagent with full project context
Agents automatically gather context via flashback agent --context
Project-aware analysis with REMEMBER.md, WORKING_PLAN.md, conversation history

Available Specialists:

architect: Systems architecture, scalability, long-term design
security: Threat modeling, vulnerability assessment
backend: APIs, reliability, data integrity
frontend: UX, accessibility, performance
database-architect: Database design, query optimization, schema evolution with proven design patterns
api-designer: REST/GraphQL API design, OpenAPI specifications, integration patterns with industry standards
data-engineer: ETL pipelines, data modeling, analytics architecture, streaming systems with proven engineering patterns
platform-engineer: Kubernetes, infrastructure-as-code, observability, developer experience with verified patterns
docker-master: Docker, Docker Compose, Swarm orchestration, networking, volumes, and containerization with expert-level knowledge
cli-master: Command-line interface design, human-machine interaction
typescript-master: Advanced TypeScript development, type system mastery
debt-hunter: Technical debt detection, code quality analysis with CLI scanning
hallucination-hunter: AI code validation, semantic correctness analysis
analyzer: Root cause analysis, investigation
mentor: Knowledge transfer, documentation
refactorer: Code quality, technical debt
performance: Optimization, bottlenecks
qa: Testing, quality assurance
devops: Infrastructure, deployment
product: User needs, business strategy
code-critic: Code quality enforcement
gpt5-cursor: GPT-5 integration for advanced analysis, second opinions, and complex problem solving
john-carmack: Performance-critical systems analysis, game engine principles, functional programming discipline

🔄 State Management

Dynamic Template Scanning: Zero hard

Flashbacker

Install / Use

README