Version: 0.3.0 (pre-release)

A terminal-based tool for building reproducible AI workflows for research, development, and analysis, featuring flexible configuration cascades, comprehensive document processing (PDFs, Office files, images), workflow dependencies and chaining, and intelligent context management.

• 🎯 Git-like Project Discovery: Automatic .workflow/ directory detection walking up from any subdirectory, enabling project-aware execution from anywhere in your tree (stops at $HOME for safety).
• 📄 Native Document Processing: Unified handling of PDFs (32MB, joint text+visual analysis), Microsoft Office files (.docx/.pptx auto-converted via LibreOffice), images (Vision API with automatic resizing), and text files with intelligent format detection and caching.
• 🔧 Configuration Cascade with Pass-Through: Multi-tier inheritance (global → ancestors → project → workflow → CLI) where empty values automatically inherit from parent tiers while explicit values override and decouple, enabling change-once affect-many configuration management.
• 🏗️ Nested Project Support: Automatic discovery and inheritance from all ancestor projects in the directory hierarchy, with transparent source tracking showing exactly where each configuration value originates.
• 🔗 Workflow Dependencies & Chaining: Create multi-stage processing pipelines with DEPENDS_ON declarations, automatically passing outputs as context to dependent workflows via hardlinks for efficient DAG-based orchestration.
• 📦 Semantic Content Aggregation: Distinguish INPUT documents (primary analysis targets) from CONTEXT materials (supporting information) using three methods: glob patterns, explicit file lists, and workflow dependencies, with optimized ordering for cost-effective caching.
• 💰 Prompt Caching Architecture: Strategic cache breakpoint placement (max 4) at semantic boundaries enables 90% cost reduction on stable content, with intelligent ordering (system prompts → project descriptions → PDFs → text → images → task) and date-only timestamps to prevent minute-by-minute invalidation.
• 📚 Citations Support: Optional Anthropic citations API integration with document mapping for source attribution, generating sidecar citation files and enabling proper references for AI-generated content.
• ⚡ Dual Execution Modes: Persistent workflows with configuration, context, dependencies, and outputs for iterative development, or lightweight task mode for one-off queries without workflow directories, both sharing optimized execution logic.
• 💾 Safe Output Management: Automatic timestamped backups before overwriting, hardlinked copies for convenient access (.workflow/output/), atomic file operations, and format-specific post-processing (mdformat, jq).
• 📊 Dual Token Estimation: Fast heuristic character-based estimates plus exact counts via Anthropic's Token Counting API, with detailed breakdowns showing contribution from system prompts, task, input documents, context, and images.
• 🌊 Streaming & Batch Modes: Real-time streaming output with SSE parsing for immediate feedback, or single-request batch mode with pager display, both supporting identical configuration and context aggregation.

First, clone the repo and then link the script into your PATH. For example:

# Clone repository
git clone https://github.com/jdmonaco/wireflow.git
cd wireflow

# Add to PATH (example using ~/.local/bin)
ln -s "$(pwd)/wireflow.sh" ~/.local/bin/wfw

export ANTHROPIC_API_KEY="sk-ant-..."
export PATH="$HOME/.local/bin:$PATH"

# Initialize project
cd my-project
wfw init .

# Create workflow
wfw new analyze-data

# Edit workflow config
wfw edit analyze-data

# Run with context
wfw run analyze-data --context-file data.csv --stream

Your project files and folders are treated as read-only. All WireFlow files are maintained in a .workflow/ subfolder.

📚 Complete documentation: https://docs.joemona.co/wireflow/

• Installation Guide: Detailed setup instructions
• Quick Start Guide: Get running in 5 minutes
• User Guide: Complete usage documentation
• CLI Reference: All commands and options
• Examples: Real-world usage patterns
• Troubleshooting: Common issues and solutions

Persistent, named tasks with configuration and outputs:

wfw new 01-analysis
wfw run 01-analysis --stream

Lightweight, one-off execution without persistence:

wfw task -i "Summarize these notes" --context-file notes.md

Chain workflows to build pipelines:

wfw run 02-report --depends-on 01-analysis --stream

Multi-tier cascade with pass-through:

Global (~/.config/wireflow/config)
    ↓
Ancestor Projects (grandparent → parent)
    ↓
Project (.workflow/config)
    ↓
Workflow (.workflow/<workflow_name>/config)
    ↓
CLI Flags (--model, --temperature, etc.)

wfw init my-analysis
wfw new analyze-data
wfw run analyze-data --context-file data.csv --stream

wfw run 00-context --stream
wfw run 01-outline --depends-on 00-context --stream
wfw run 02-draft --depends-on 00-context,01-outline --stream

wfw task -i "Extract action items" --context-file meeting-notes.md

• Bash 4.0+
• curl and jq
• Anthropic API key (get one here)

Auto-created on first use at ~/.config/wireflow/:

• config - Global defaults for all projects
• prompts/base.txt - Default system prompt
• tasks/ - Named task templates (optional)

Created by wfw init:

• .workflow/config - Project-level settings
• .workflow/project.txt - Project description (optional)
• .workflow/<workflow-name>/ - Individual workflows

wfw help              # Show all subcommands
wfw help <subcommand> # Detailed subcommand help
wfw <subcommand> -h   # Quick help

Contributions welcome! See CONTRIBUTING.md for guidelines.

MIT License - see LICENSE for details.

• GitHub: https://github.com/jdmonaco/wireflow
• Issues: GitHub Issues
• Anthropic API: https://docs.anthropic.com/
• Technical Details: CLAUDE.md

Made with Claude Code