The fastest, simplest screen capture for developers - Python-first CLI tool

A lightweight CLI tool for instant screen capture, GIF recording, and AI session integration. Built for developers who need automation-friendly, cross-platform screen recording without the GUI overhead.

• CLI-First: No GUI overhead - perfect for automation and scripting
• Python Native: import flashrecord - use in your scripts directly
• One-Command Simplicity: @sc for screenshots, @sv for GIF recording
• Zero Configuration: Works out of the box with sensible defaults
• Cross-Platform: Windows, macOS, Linux - same commands everywhere

Key Differentiator: FlashRecord is the only Python-native, cross-platform screen recorder with direct scripting integration. Perfect for test automation, documentation workflows, and CI/CD pipelines.

• Native Screenshot - Instant screen capture with Pillow/PIL (no external tools needed)
• Screen Recording to GIF - One-command full screen recording with imageio + numpy
• Intelligent Compression - 99.5% file size reduction with RGB color preservation
  • CWAM-inspired approach (arXiv:2410.21144) implemented purely in Python
  • Cross-window saliency analysis (multi-scale feature extraction)
  • Temporal subsampling (10fps → 8fps) and adaptive resolution scaling
  • Saliency-based quality preservation (variance + edge density + entropy)
  • No ML models required - pure PIL/NumPy implementation
• AI Integration - Save sessions for Claude, Gemini, Codex
• Auto-Cleanup - Delete files older than N hours
• Cross-Platform - Windows, macOS, Linux (native support for each)
• Production Ready - Full CI/CD, pytest suite, Sphinx docs, PyPI-ready structure

# From PyPI (recommended - coming soon)
pip install flashrecord

# From source
git clone https://github.com/Flamehaven/flashrecord.git
cd flashrecord
pip install -e .

# Or with Poetry
poetry install

# Python 3.8+
python --version

# Core dependencies (auto-installed):
# - pillow>=9.0.0 (native screenshot capture)
# - imageio>=2.0.0 (GIF encoding with compression)
# - numpy>=1.20.0 (frame processing and saliency analysis)

# Run CLI
flashrecord

# Or with Python module
python -m flashrecord.cli

# Direct commands
flashrecord @sc              # Screenshot
flashrecord @sv 10 10        # 10-second GIF at 10 FPS

Choose your preferred style during setup or edit config.json:

> 1              # Start recording
> 2              # Stop recording
> 3              # Convert to GIF
> 4              # Save to claude.md
> 5              # Save to gemini.md
> 6              # Save to codex.md

> vs             # Video Start
> vc             # Video Capture (stop)
> vg             # Video Gif
> cs             # Claude Save
> cg             # Gemini Save
> cz             # Codex Save

> start          # Start recording
> stop           # Stop recording
> gif            # Convert to GIF
> claude         # Save to claude.md
> gemini         # Save to gemini.md
> codex          # Save to codex.md

New in v0.3.0: @sv now records full screen directly to GIF with interactive duration input and CWAM-inspired compression.

> @sc
[+] Screenshot: output/screenshot_20251026_143022.png

> @sv
[?] Recording duration in seconds (default: 5): 10
[>] Recording screen for 10 seconds...
[██████████] 100% (10.0s)
[+] Encoding GIF...
[*] CWAM-inspired compression: 100 frames
[*] Resolution scaling: (1920, 1080) -> (960, 540)
[*] Temporal subsampling: 100 -> 80 frames (10fps -> 8fps)
[+] Compression complete: 100 -> 80 frames
[+] GIF saved: output/screen_20251026_143045.gif
[+] Size: 0.2 MB, 100 frames, 10.0s

from flashrecord.screenshot import take_screenshot
from flashrecord.screen_recorder import record_screen_to_gif

# Automated screenshot
screenshot_path = take_screenshot(output_dir='./screenshots')

# Automated GIF recording
gif_path = record_screen_to_gif(
    duration=5,
    fps=10,
    compression='balanced',
    output_dir='./gifs'
)

All files save to output/ (flat structure):

output/
├── screenshot_*.png        # Screenshots (@sc command)
├── screen_*.gif            # Screen recordings (@sv command)
├── claude.md               # Claude sessions
├── gemini.md               # Gemini sessions
├── codex.md                # Codex sessions
└── general.md              # General sessions

Edit config.json to customize:

{
  "command_style": "numbered",
  "auto_delete_hours": 24
}

• command_style: "numbered", "vs_vc_vg", or "verbose"
• auto_delete_hours: Auto-delete files older than N hours (0 = disabled)

Add workflow instructions to markdown files in output/:

Option 1: HTML Comments

<!-- instructions:start -->
Your instructions here
<!-- instructions:end -->

Option 2: Heading Section

## Instructions
Your instructions here

Instructions display at startup for quick reference.

Fix: Ensure Pillow is installed:

pip install pillow>=9.0.0

Fix: Ensure imageio and numpy are installed:

pip install imageio>=2.0.0 numpy>=1.20.0

Fix: Install platform-specific screenshot tools:

# Ubuntu/Debian
sudo apt-get install gnome-screenshot

# macOS (usually pre-installed)
which screencapture

# Fedora
sudo dnf install gnome-screenshot

• Screenshot Capture: ~10-50ms (native Pillow, platform-dependent)
  • Windows: ~15-30ms (ImageGrab)
  • macOS: ~20-50ms (screencapture command)
  • Linux: ~20-50ms (gnome-screenshot/scrot)
• Screen Recording to GIF: 10 FPS capture with real-time progress
• CWAM Compression: 99.5% size reduction (25.6 MB → 0.1 MB for 5s/50 frames)
  • Resolution scaling: 50% (1920x1080 → 960x540)
  • Temporal subsampling: 10fps → 8fps (20% frame reduction)
  • RGB color preservation: Full color fidelity maintained
• Session Save: ~50ms
• File Cleanup: ~100ms
• No external process overhead (integrated implementation)

flashrecord/                  # Project root
├── src/                      # Source code (Python Packaging Guide standard)
│   └── flashrecord/          # Main package
│       ├── __init__.py
│       ├── cli.py            # Main CLI interface
│       ├── screenshot.py     # Native screenshot capture (Pillow)
│       ├── screen_recorder.py # Screen to GIF recorder (imageio)
│       ├── compression.py    # CWAM-inspired GIF compression
│       ├── config.py         # Configuration management
│       ├── ai_prompt.py      # AI session manager
│       ├── manager.py        # File lifecycle
│       └── utils.py          # Utilities
├── output/                   # Auto-created output directory
├── tests/                    # Test suite (pytest)
├── docs/                     # Sphinx documentation
├── .github/                  # GitHub Actions CI/CD
│   └── workflows/
│       └── ci.yml
├── pyproject.toml            # Poetry configuration
├── config.json               # User configuration
├── .gitignore                # Git ignore rules
├── README.md                 # This file
└── CHANGELOG.md              # Version history

from flashrecord import FlashRecordCLI

cli = FlashRecordCLI()
cli.run()

from flashrecord.screenshot import take_screenshot

path = take_screenshot()  # Saves to flashrecord-save/screenshot_*.png

from flashrecord.screen_recorder import record_screen_to_gif

# Record with CWAM compression
gif_path = record_screen_to_gif(
    duration=5,           # seconds
    fps=10,               # frames per second
    compression='balanced',  # 'high', 'balanced', 'compact'
    output_dir='flashrecord-save'
)
# Returns: flashrecord-save/screen_20251025_143045.gif

from flashrecord.config import Config

config = Config()
print(config.save_dir)           # Output directory
print(config.command_style)      # Current command style
print(config.auto_delete_hours)  # Auto-cleanup threshold

from flashrecord.ai_prompt import AIPromptManager

manager = AIPromptManager()
manager.save_session("claude")   # Save session timestamp
notes = manager.get_instruction_notes()  # Load workflow notes

"The fastest, simplest screen capture for developers"

FlashRecord is built for developers who need reliable, scriptable screen recording without GUI overhead. Our mission is to be the Python ecosystem's go-to tool for screen capture automation.

1. Python-Native Integration: The only screen recorder you can import and use directly in Python scripts
2. Intelligent Compression: CWAM-inspired approach achieving 99.5% reduction with pure PIL/NumPy (no ML models)
3. Zero-Configuration CLI: @sc and @sv - that's it
4. Cross-Platform Consistency: Same commands, same behavior on Windows/macOS/Linux
5. Production-Ready: Full CI/CD, pytest coverage, Sphinx docs, PyPI structure

v0.4.0 - Enhanced Formats (Planned Q1 2025)

v0.5.0 - GUI & Integration (Planned Q2 2025)

v0.6.0 - Advanced Features (Planned Q3 2025)

v1.0.0 - Enterprise (Planned Q4 2025)

1. Active Use: FlashRecord is battle-tested in production AI development workflows
2. Clear Architecture: Standard src/ layout, comprehensive tests, full CI/CD
3. PyPI Ready: Professional packaging structure ready for public release
4. Community Need: Fills gap for Python-native cross-platform screen recording

MIT License - See LICENSE file

We welcome contributions! See our development setup:

# Clone repository
git clone https://github.com/Flamehaven/flashrecord.git
cd flashrecord

# Install development dependencies
poetry install --with dev

# Run tests
poetry run pytest tests/ -v

# Build documentation
cd docs && poetry run sphinx-build -b html . _build

Flamehaven - AI Development Framework

• Issues: GitHub Issues for bug reports and feature requests
• Documentation: Full Sphinx docs at docs/ directory
• Examples: Check tests/ for usage examples