🎨 Fabric TUI

A beautiful terminal interface for fabric-ai

Less typing, more piping.

Features • Installation • Quick Start • Usage • Configuration • Keybindings • Project Structure • Development

---

🎯 Why Fabric TUI?

Working with fabric-ai's powerful patterns is amazing, but remembering all the CLI flags and options? Not so much. Fabric TUI gives you a visual, interactive interface with:

• 🔍 Fuzzy search - Find patterns, strategies, and contexts instantly
• ⛓️ Pipeline builder - Chain multiple patterns together visually
• 🎹 Vim-style navigation - Because your hands shouldn't leave home row
• 📦 Zero config - Automatically discovers your fabric installation
• 🚀 Live execution - Preview and run commands directly in your terminal

✨ Features

🎨 Interactive Pattern Selection

Browse and search through all your fabric patterns with fuzzy filtering. No more scrolling through --help output.

🔗 Visual Pipeline Building

Chain multiple patterns together with a simple keypress. See your entire pipeline before execution:

echo "prompt" | fabric -p summarize | fabric -p improve_writing | fabric -p add_emojis

🎯 Strategy & Context Management

• Select from all available strategies (chain-of-thought, few-shot, etc.)
• Apply multiple contexts from your fabric configuration
• Toggle flags with visual feedback

🔄 Smart Discovery

Automatically finds patterns, strategies, and contexts from:

• Your $FABRIC_ROOT environment variable
• Standard fabric locations (~/.config/fabric, ~/Fabric, etc.)
• Custom paths in your config
• Dynamic CLI discovery via fabric --list* commands

🎹 Vim-Style Navigation

Navigate with hjkl, filter with /, toggle with space - all the keybindings you'd expect from a well-designed TUI.

📦 Installation

Prerequisites

• Python 3.10 or higher
• fabric-ai or fabric CLI installed

Quick Install

# Clone the repository
git clone https://github.com/stephenmcgurrin/fabric-tui.git
cd fabric-tui

# Install the package
uv pip install .

# Now run the CLI command directly
fabric-tui

Fabric TUI uses only the Python standard library (curses), so there are no external dependencies for running.

Development Install

# Clone and install in editable mode with dev dependencies
git clone https://github.com/stephenmcgurrin/fabric-tui.git
cd fabric-tui
uv venv
uv pip install -e ".[dev]"

# Run the installed command
fabric-tui

# Or run as a module
python -m fabric_tui

Legacy Entry Point

For historical reference, the original monolithic script is preserved in archive/fabric_tui.py but is no longer the recommended way to run the application. After installation, always use the fabric-tui command instead.

🚀 Quick Start

Basic Usage

# Launch the TUI (recommended - uses the installed CLI command)
fabric-tui

# Use a custom config
fabric-tui --config ~/my-fabric-config.json

# Override fabric roots
fabric-tui --fabric-root ~/my-patterns --fabric-root ~/Fabric

# Alternatively, run as a Python module
python -m fabric_tui

Your First Pipeline

1. Launch Fabric TUI
2. Select a pattern - Use j/k to navigate, / to filter, enter to select
3. Add your prompt - Press l to move to Prompt section, i to edit
4. Run it - Press r to execute in your terminal

Want to chain patterns? Press | to add a new stage, select another pattern, and press r to run the entire pipeline!

📖 Usage

Command Line Options

fabric-tui [OPTIONS]

Options:
  --config PATH          Path to config file (default: ./fabric_tui_config.json)
  --fabric-root PATH     Discovery root path (can be repeated, overrides config)
  --fabric-cmd PATH      Fabric executable path (default: auto-detect)
  --print-discovery      Print discovered patterns/strategies/flags and exit

Discovery Inspection

See what Fabric TUI found:

fabric-tui --print-discovery

Output:

Config: /Users/you/fabric_tui_config.json
Fabric command: fabric-ai
Discovery roots:
  - /Users/you/Fabric

Patterns (42):
  - summarize
  - improve_writing
  - extract_wisdom
  ...

Strategies (8):
  - chain-of-thought: Think step by step
  - few-shot: Learn from examples
  ...

Building Complex Pipelines

Fabric TUI excels at building multi-stage pipelines:

1. Press | to create a new pipeline stage
2. Select pattern for each stage
3. Configure strategies/contexts per stage
4. Press r to execute: stage1 | stage2 | stage3

Each stage maintains independent configuration:

• Pattern selection
• Strategy
• Contexts
• Flags
• Extra arguments

Working with Flags

Fabric TUI automatically parses all available flags from fabric --help:

1. Navigate to the Flags section (l until you reach it)
2. Filter flags with /
3. Toggle boolean flags with space
4. For value-taking flags: space opens an input prompt
5. Press u to uncheck/remove a flag

⚙️ Configuration

Config File Format

Create fabric_tui_config.json in your working directory:

{
  "fabric_cmd": "fabric-ai",
  "locations": [
    "$FABRIC_ROOT",
    "~/.config/fabric",
    "~/.fabric-config",
    "~/Fabric",
    "~/fabric"
  ],
  "additional_locations": [
    "~/my-custom-patterns",
    "/path/to/shared/patterns"
  ]
}

Configuration Options

Option	Type	Description
fabric_cmd	string	Fabric executable name or full path
locations	array	Standard fabric location paths
additional_locations	array	Additional custom pattern locations

Path Resolution

• $FABRIC_ROOT expands from environment variable
• ~ expands to home directory
• Relative paths resolve from config file directory
• If no paths exist, falls back to current directory

⌨️ Keybindings

Navigation

Key	Action
h / l / ← / → / Tab	Switch between sections
j / k / ↓ / ↑	Move selection up/down
[ / ]	Switch to previous/next pipeline stage

Filtering & Editing

Key	Action
/	Start fuzzy filter (in Pattern/Strategy/Context/Flags)
i	Edit current item (Prompt/Extra Args/Flag values)
Enter	Confirm filter/edit, or activate current item
Esc	Cancel filter/edit mode

Selection & Modification

Key	Action
Space	Toggle/select current item
u	Uncheck/remove current item
Enter	Activate current item (context-sensitive)

Pipeline Management

Key	Action
|	Add new pipeline stage
[	Switch to previous stage
]	Switch to next stage

Execution

Key	Action
r	Run command in terminal with live output
c	Clear run preview
q	Quit

🎯 Tips & Tricks

Workflow Optimization

1. Use fuzzy filtering - Type just a few characters to find patterns quickly
2. Build reusable pipelines - Create common chains like summarize | improve_writing
3. Leverage contexts - Apply domain-specific knowledge consistently
4. Preview before running - Check the command preview at the bottom

Advanced Patterns

Multi-stage refinement:

Stage 1: extract_wisdom (get key points)
Stage 2: improve_writing (enhance clarity)
Stage 3: create_summary (condense result)

Context-aware processing:

• Add technical context for code-related prompts
• Include domain context for specialized topics
• Combine multiple contexts for nuanced understanding

🏗️ Project Structure

The codebase follows a modular package architecture:

fabric-tui/
├── pyproject.toml             # Package metadata and build configuration
├── fabric_tui/                # Main package
│   ├── __init__.py            # Package version and exports
│   ├── __main__.py            # python -m fabric_tui entry point
│   ├── cli.py                 # CLI argument parsing and main() function
│   ├── models.py              # Data models (AppConfig, StageSelection, etc.)
│   ├── config.py              # Configuration loading and path resolution
│   ├── discovery.py           # Pattern, context, strategy, and flag discovery
│   ├── command_builder.py     # Pipeline command construction
│   ├── executor.py            # Command execution logic
│   ├── filtering.py           # Fuzzy search and filtering
│   ├── utils.py               # Shared utility functions
│   └── ui/                    # Terminal UI components
│       ├── __init__.py
│       ├── tui.py             # Main FabricTUI class (assembles mixins)
│       ├── drawing.py         # DrawingMixin — all rendering/drawing methods
│       └── handlers.py        # Input handling mixin — key dispatch and actions
├── tests/                     # Test suite
│   ├── __init__.py
│   ├── test_filtering.py      # Fuzzy search tests
│   ├── test_discovery.py      # Discovery logic tests
│   ├── test_config.py         # Configuration loading tests
│   ├── test_command_builder.py # Command construction tests
│   └── test_utils.py          # Utility function tests
└── archive/                   # Historical reference
    └── fabric_tui.py          # Original monolithic script (preserved for reference)

Module Responsibilities

Module	Purpose
models.py	Pure data structures — AppConfig, StageSelection, FlagOption, etc.
config.py	Loads JSON config, resolves paths, provides defaults
discovery.py	Discovers patterns, contexts, strategies, and flags from the filesystem and CLI
command_builder.py	Constructs shell commands from pipeline stage selections
executor.py	Runs commands via subprocess with live output
filtering.py	Fuzzy scoring and list filtering
utils.py	Shared helpers (directory scanning, subprocess wrappers)
ui/tui.py	Assembles the FabricTUI class from mixin components
ui/drawing.py	Screen rendering — panels, lists, status bar, preview
ui/handlers.py	Keyboard input dispatch, cursor movement, editing

🧪 Development

Setting Up

git clone https://github.com/stephenmcgurrin/fabric-tui.git
cd fabric-tui

# Create a virtual environment with uv
uv venv
uv pip install -e ".[dev]"

Running Tests

# Run the full test suite
pytest tests/

# Run with verbose output
pytest tests/ -v

# Run a specific test file
pytest tests/test_filtering.py

Running the App in Development

# Using the installed CLI command (recommended)
fabric-tui

# Or using package invocation (uses __main__.py → cli.py)
python -m fabric_tui

🤝 Contributing

Contributions are welcome! The codebase has been refactored from a single file into a modular package to make it easier to understand, test, and extend.

Ideas for contributions:

• Additional keybinding schemes
• Color scheme support
• Export/import pipeline configurations
• Pattern usage statistics
• Better error handling

📄 License

MIT License - feel free to use this in your own projects!

🙏 Acknowledgments

• Built for fabric-ai by Daniel Miessler
• Inspired by modern TUI applications like lazygit and k9s
• Uses Python's curses library for the terminal interface - curses for good, not evil

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Fabric: Fabric GitHub

---

⬆ back to top

Made with ❤️ for the Fabric community