███████╗██╗      █████╗ ███████╗██╗  ██╗██████╗  █████╗  ██████╗██╗  ██╗███████╗██████╗ 
██╔════╝██║     ██╔══██╗██╔════╝██║  ██║██╔══██╗██╔══██╗██╔════╝██║ ██╔╝██╔════╝██╔══██╗
█████╗  ██║     ███████║███████╗███████║██████╔╝███████║██║     █████╔╝ █████╗  ██████╔╝
██╔══╝  ██║     ██╔══██║╚════██║██╔══██║██╔══██╗██╔══██║██║     ██╔═██╗ ██╔══╝  ██╔══██╗
██║     ███████╗██║  ██║███████║██║  ██║██████╔╝██║  ██║╚██████╗██║  ██╗███████╗██║  ██║
╚═╝     ╚══════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═════╝ ╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝
                                                                                          
         ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
       ░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░
     ░░▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒░░
   ░░▒▒▓▓██████████████████████████████████████████████████████████████████▓▓▒▒░░
 ░░▒▒▓▓████  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:

1. Session continuity for Claude Code through intelligent state management memory commands
2. Specialized AI personas accessed via /fb: slash commands
3. Dedicated agents accessed via @agent-{AGENT-NAME} commands
4. Agent discussion system for complex issues
5. A code task management system for complex issues
6. 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"):

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

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

1. Agent spawning: Claude Code spawns dedicated architect subagent
2. Context gathering: Agent runs flashback agent --context to get project bundle
3. Rich context: Agent receives REMEMBER.md, WORKING_PLAN.md, conversation history
4. 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 hardcoded paths, everything from bundled templates
• Memory System: Persistent project knowledge across sessions
• Working Plan: AI-powered development priority tracking

🔌 MCP Server Integration

• context7: Up-to-date documentation and library context for any framework
• playwright: Browser automation, testing, and web interaction capabilities
• sequential-thinking: Advanced multi-step reasoning and problem-solving chains

🧩 Background Daemon (PM2)

• PM2 auto-install: ensured during install via postinstall/prereqs/installer
• Per-project daemon: flashback init generates .claude/flashback/scripts/pm2/ecosystem.config.js
• Start/stop/status/logs:
  • flashback daemon --start
  • flashback daemon --stop
  • flashback daemon --status
  • flashback daemon --logs
• Naming: PM2 app name uses your project_name from flashback.json (sanitized)

🎯 Slash Commands You'll Use

Persona Analysis (Current Conversation)

/fb:persona architect "should we refactor the database layer?"
/fb:persona security "review authentication in src/auth/"
/fb:persona database-architect "optimize our PostgreSQL schema and indexes"
/fb:persona api-designer "design GraphQL schema for user management"
/fb:persona data-engineer "review our Apache Kafka streaming pipeline"
/fb:persona platform-engineer "Kubernetes deployment and scaling strategy"
/fb:persona docker-master "optimize container deployment and orchestration"
/fb:persona performance "optimize our query performance"
/fb:persona qa "what edge cases should we test?"
/fb:persona john-carmack "analyze hot path performance and control flow"

Agent Analysis (Dedicated Subagents)

@agent-architect "analyze our microservices architecture"
@agent-security "comprehensive security audit of auth system"
@agent-database-architect "database design review with optimization recommendations"
@agent-api-designer "REST API standards compliance and OpenAPI specification"
@agent-data-engineer "ETL pipeline performance and data quality analysis"
@agent-platform-engineer "infrastructure-as-code review and DevOps optimization"
@agent-docker-master "comprehensive containerization strategy and deployment optimization"
@agent-performance "deep performance analysis with recommendations"
@agent-qa "create comprehensive testing strategy"

Session Management

/fb:working-plan          # Update development plan with AI analysis
/fb:save-session         # Capture session insights before compaction
/fb:session-start        # Load project context (runs automatically via hook)
/fb:how                  # Implementation planning prompt (plan before coding)
/fb:how "specific topic"         # Focused planning for specific topic only
/fb:remember important insight here  # Add key information to project memory
/fb:persona-list         # Show all available AI personas with descriptions
/fb:agents-list          # Show all available Claude Code agents with descriptions
/fb:discuss architect,security "topic"  # Multi-agent discussion coordination

Multi-Language Code Quality Analysis

/fb:debt-hunter                      # Hunt technical debt across 6 programming languages
/fb:debt-hunter duplicates           # Focus on duplicate function detection
/fb:debt-hunter comprehensive        # Full analysis (debt + duplicates)
/fb:hallucination-hunter             # Hunt AI-generated code that doesn't actually work

# Automatically detects and analyzes:
# - JavaScript/TypeScript: console.log(), debugger;, empty functions
# - Python: print(), pdb.set_trace(), NotImplementedError
# - Go: fmt.Println(), panic(), runtime.Breakpoint()
# - Java: System.out.println(), UnsupportedOperationException
# - Rust: println!(), panic!(), unimplemented!()
# - Universal patterns: TODO comments, generic names, similar functions

Memory Management

# Add key information to project memory:
/fb:remember important architectural decision about database design

# View current project memory:
flashback memory --show

🏗️ How It Works

1. Installation & Setup

• Run flashback init --mcp once per project (recommended)
• Creates .claude/flashback/ directory structure
• Installs SessionStart hook for automatic context loading
• Configures powerful MCP servers for enhanced capabilities

2. Daily Usage

• Use /fb:persona <name> "request" for specialized analysis
• Use /fb:working-plan to keep development priorities current
• Use /fb:save-session before major context compactions
• Memory automatically loads via SessionStart hook

3. Behind the Scenes

• CLI: Gathers project context, loads templates, formats prompts
• Claude: Executes Task tool with specialized persona prompts
• Hybrid Pattern: Computer handles data, AI handles intelligence

🔧 Advanced Features

Discussion System

# CLI command for multi-agent analysis (READ ONLY recommended):
flashback discuss "Should we use microservices?" john-carmack,architect,devops,security

# In-conversation multi-agent discussions:
/fb:discuss architect,security,performance "review this authentication implementation"

Diagnostics (When Things Go Wrong)

flashback doctor          # Check system health
flashback status          # Verify installation
flashback init --refresh  # Update templates
flashback init --mcp      # Add MCP servers to existing setup

🏗️ Architecture

Template-Driven System

• Dynamic Directory Scanning: Reads bundled templates at runtime
• Zero Hardcoded Paths: All structure derived from template bundle
• Variable Replacement: {{PROJECT_NAME}}, {{VERSION}}, {{TIMESTAMP}}
• Version Sync: Automatically uses package.json version

Hybrid AI+Computer Operations

• CLI: Handles programmatic operations (file management, data extraction)
• AI: Handles intelligence operations (analysis, planning, decisions)
• Clear Separation: Computer does deterministic work, AI does creative work

🔧 Requirements

• Node.js 18.x-22.x LTS: Required for tree-sitter native modules and modern features
• npm 9.x+: Required for lockfile version 3 support
• Claude Code: Latest version for hook system compatibility

⚠️ Note: Versions outside the Node.js 18-22 range may cause native module compilation errors.

🔒 Security

Flashbacker automatically excludes .claude/ from git commits to protect sensitive data.

📄 License

MIT License

v2.4.1 Status: 🚧 ALPHA - Complete Workflow System + 20 Total Specialists. Statusline now writes state at the git repository root and init installs to the repo root even when run from nested subdirectories. Templates auto-overwrite on refresh. Restored /fb:create-issue command for comprehensive issue documentation from working plan insights.

🙏 Acknowledgments

This project draws inspiration and prompts from:

• SuperClaude Framework - Advanced AI persona system concepts
• CCPlugins - Some excellent prompt inspiration