ThinkFlow 🧠✨

A modern, voice-first thought capture application with real-time transcription, daemon optimization, and powerful data management tools.

ThinkFlow is a sophisticated command-line tool designed to seamlessly capture your thoughts through multiple input methods. Whether you prefer typing, traditional voice recording, or real-time speech capture, ThinkFlow provides a responsive interface with state-of-the-art voice transcription powered by OpenAI Whisper. All thoughts are stored locally in a SQLite database and can be easily managed, searched, and edited using an efficient, fzf-powered workflow.

✨ Key Features

🎤 Advanced Voice Capture

Live Voice Capture: Real-time transcription with Voice Activity Detection (VAD) and automatic silence detection
JIT Daemon: Just-In-Time model caching for instant voice processing with zero startup delay
GPU Acceleration: High-performance transcription using faster-whisper with CUDA optimization
Multilingual Support: Optimized for Dutch and English with automatic language detection
Background Enhancement: Automatic transcription improvement using multiple model tiers

📝 Multiple Input Methods

Text Capture: Quick text input with validation
Voice Recording: Traditional voice recording with transcription
Live Transcription: Real-time speech-to-text with visual feedback
File Processing: Import and transcribe existing audio files

🔧 System Features

Beautiful Terminal UI: Built with Rich for elegant progress bars, panels, and tables
Interactive Data Management: fzf-powered commands to list, search, edit, and delete thoughts
Robust Configuration: Hierarchical configuration system (YAML files, environment variables, CLI arguments)
Privacy First: All data stored locally in SQLite database
AI Integration: Built-in support for LLM interactions and thought enhancement

🚀 Getting Started

Prerequisites

Before installing, ensure you have the necessary system dependencies:

General

fzf: Required for interactive menus (list, edit, delete)
- On Debian/Ubuntu: sudo apt-get install fzf
- On macOS: brew install fzf

Audio Processing

PortAudio: Required by pyaudio for microphone recording
- On Debian/Ubuntu: sudo apt-get install portaudio19-dev
- On macOS: brew install portaudio
FFmpeg: Required for processing audio file formats
- On Debian/Ubuntu: sudo apt-get install ffmpeg
- On macOS: brew install ffmpeg

GPU Acceleration (Optional)

For high-performance transcription, an NVIDIA GPU is recommended:

NVIDIA Driver: Recent NVIDIA driver
CUDA Toolkit: faster-whisper is optimized for CUDA 12
cuDNN: cuDNN 9 is required for CUDA 12 support

Note: If CUDA libraries are not detected, ThinkFlow will automatically fall back to CPU mode.

Installation

It is highly recommended to install ThinkFlow in a dedicated virtual environment:

# Clone the repository
git clone https://github.com/givani30/thinkflow.git
cd thinkflow

# Create and activate a virtual environment (using uv)
uv venv
source .venv/bin/activate

# Install the package and dependencies
uv pip install -e .

Database Initialization

The first time you run any command, the thinkflow.db SQLite database will be created in your current directory.

💻 Usage

ThinkFlow provides a simple and powerful command-line interface.

Quick Start with Daemon (Recommended)

For optimal performance, start the daemon first to enable instant voice processing:

# Start the daemon in background for optimized performance
thinkflow daemon start

# Capture thoughts with zero startup delay
thinkflow live                                  # Real-time transcription
thinkflow voice --max-duration 60              # Traditional recording

# Check daemon status
thinkflow daemon status

Core Commands

Capturing Thoughts

# 💬 Capture a simple text thought
thinkflow capture "My new idea is to build a CLI app."

# 🎤 Live voice capture with real-time transcription (auto-stops on silence)
thinkflow live --silence-timeout 2.0

# 🎙️ Traditional voice recording (press Enter to stop)
thinkflow voice --max-duration 300

# 📁 Transcribe an existing audio file
thinkflow voice-file /path/to/recording.mp3 --language en

Managing Thoughts

ThinkFlow uses fzf for efficient, interactive data management:

# 📋 List all thoughts in an fzf-compatible format
thinkflow list

# 🔍 Search for thoughts containing specific keywords
thinkflow search "keyword"

# ✏️ Interactively select and edit a thought
thinkflow edit

# 🗑️ Interactively select and delete a thought (with confirmation)
thinkflow delete

Daemon Management

# Start the daemon in background (recommended)
thinkflow daemon start

# Start the daemon in foreground
thinkflow daemon start --no-background

# Check daemon status with detailed information
thinkflow daemon status

# Stop the running daemon
thinkflow daemon stop

# Restart the daemon
thinkflow daemon restart

# Legacy command (still works)
thinkflow daemon

Command Options

Most commands support common options:

--language: Language code (en, nl, etc.) or None for auto-detect
--force-cpu: Force CPU usage even if GPU available
--max-duration: Maximum recording duration in seconds
--silence-timeout: Seconds of silence before auto-stop (live capture)

🔧 Configuration

ThinkFlow is highly configurable. You can view and manage settings using the config subcommand:

# Show current configuration from all sources
thinkflow config show

# Get a specific value
thinkflow config get voice.models.gpu_model

# Set a new value (auto-saved to config file)
thinkflow config set cli.language "en"
thinkflow config set voice.models.gpu_model "large-v3"

# Open config file in your default editor
thinkflow config edit

# Reset configuration to defaults
thinkflow config reset

Configuration Hierarchy

Settings are loaded with this priority (highest to lowest):

Command-line arguments (--force-cpu)
Environment variables (THINKFLOW_VOICE_FORCE_CPU=true)
YAML configuration file (~/.config/thinkflow/config.yaml)
Built-in default values

Quick Configuration Examples

# Set default language for all commands
thinkflow config set cli.language "en"

# Use larger model for better quality
thinkflow config set voice.models.gpu_model "large-v3"

# Adjust live capture sensitivity
thinkflow config set live_capture.silence_timeout 3.0

For detailed configuration options, see Configuration Guide.

⚡ Performance with Daemon

ThinkFlow includes a JIT (Just-In-Time) caching daemon that dramatically improves voice capture performance:

Benefits

Zero startup delay: Models stay loaded in memory
Instant transcription: No model loading time
Background enhancement: Automatic quality improvements
Memory efficient: Smart model management with timeouts

Usage

# Start daemon in background (recommended)
thinkflow daemon start

# All voice commands now use optimized processing
thinkflow live    # ✅ Instant startup
thinkflow voice   # ✅ Instant startup

# Check daemon status anytime
thinkflow daemon status

# Stop when done
thinkflow daemon stop

For advanced daemon usage and troubleshooting, see Daemon Guide.

🤖 AI Integration

ThinkFlow includes foundational AI capabilities for thought enhancement:

Magic Suffixes

Add special suffixes to trigger AI interactions:

thinkflow capture "My project idea needs work +"     # Enhance
thinkflow capture "This plan might have issues -"    # Critique
thinkflow capture "Long detailed thoughts here ~"    # Summarize

AI Providers

ThinkFlow supports multiple AI providers through CLI tools:

Gemini: gemini command-line tool
Claude: claude command-line tool
Custom: Extensible provider system

Note: AI features require separate installation of provider CLI tools.

🏗️ Architecture

ThinkFlow features a modern, modular architecture:

CLI Interface: Built with Typer and Rich for beautiful command-line interaction
JIT Daemon: FastAPI-based background service for model caching and optimization
Capture Providers: Modular system supporting text, voice, and live capture methods
Database Layer: SQLModel-based persistence with SQLite backend
Configuration System: YAML-based configuration with environment variable support

🧪 Development

Setup Development Environment

# Install development dependencies
uv pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

# Run the full test suite
pytest

# Run with coverage report
pytest --cov=src/thinkflow

# Run specific test categories
pytest tests/capture/          # Capture provider tests
pytest tests/test_cli_*        # CLI integration tests

Key Technologies

CLI Framework: Typer
UI: Rich
Database: SQLModel + SQLite
Voice Transcription: faster-whisper
Live Audio: sounddevice
Daemon: FastAPI + asyncio
Packaging: uv

For detailed development information, see Development Guide.

📚 Documentation

Configuration Guide - Detailed configuration options and examples
Daemon Guide - Advanced daemon usage and troubleshooting
Development Guide - Contributing and development setup

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

OpenAI Whisper - For excellent speech recognition models
faster-whisper - For optimized inference implementation
Rich - For beautiful terminal UI components
Typer - For elegant CLI framework
FastAPI - For high-performance daemon API

Built with ❤️ for seamless thought capture

Name		Name	Last commit message	Last commit date
Latest commit History 70 Commits
.github/instructions		.github/instructions
.taskmaster		.taskmaster
alembic		alembic
data		data
docs		docs
scripts		scripts
src/thinkflow		src/thinkflow
tests		tests
whisper_playground		whisper_playground
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
CLAUDE.md		CLAUDE.md
DOCUMENTATION_CLEANUP.md		DOCUMENTATION_CLEANUP.md
FEATURES_REFERENCE.md		FEATURES_REFERENCE.md
GEMINI.md		GEMINI.md
README.md		README.md
THINKFLOW_2.0_PLAN.md		THINKFLOW_2.0_PLAN.md
alembic.ini		alembic.ini
config.example.yaml		config.example.yaml
main.py		main.py
package-lock.json		package-lock.json
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
sample.wav		sample.wav
t		t
uv.lock		uv.lock
w		w

givani30/ThinkFlow

Folders and files

Latest commit

History

Repository files navigation