term-flow/.README.md

Term Flow

A CLI tool that records terminal sessions and generates ASCII flowcharts/visualizations. Perfect for documenting workflows, creating tutorials, and visualizing git histories.

Features

• Session Recording: Record terminal sessions interactively or from shell history
• Flowchart Generation: Generate ASCII and Mermaid diagrams from recorded sessions
• Git Visualization: Visualize git workflows and commit histories
• Pattern Detection: Automatically detect common command patterns
• Session Comparison: Compare multiple terminal sessions side by side
• Export Options: Export to various formats including ASCII, JSON, and Mermaid

Installation

pip install termflow

Or from source:

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/term-flow.git
cd term-flow
pip install -e .

Quick Start

Record a Session

# Interactive recording
termflow record

# Record from shell history
termflow record --from-history --count 100

# Record with custom name
termflow record my-session-name

List Recorded Sessions

termflow list

Visualize a Session

# Visualize latest session as ASCII
termflow visualize session

# Visualize with specific style
termflow visualize session --style detailed --format ascii

# Visualize as Mermaid diagram
termflow visualize session --format mermaid -o session.mmd

Visualize Git Workflow

# Visualize current git repository
termflow visualize git

# Export git visualization
termflow visualize git --format mermaid -o git-graph.mmd

Compare Sessions

# Compare two sessions
termflow compare --sessions 1 2

# Compare all sessions
termflow compare --all

Export a Session

# Export to JSON
termflow export session --session-id 1 --format json -o session.json

# Export to ASCII
termflow export session --format ascii -o session.txt

Commands

record

Record a terminal session.

termflow record [NAME] [OPTIONS]

Options:

• --interactive/--no-interactive: Run in interactive mode (default: True)
• --from-history: Record from shell history
• --count: Number of history commands to record (default: 50)
• --output, -o: Output file for session export

visualize

Visualize a session or git workflow.

termflow visualize <source> [OPTIONS]

Sources:

• session: Visualize a recorded session
• git: Visualize git workflow

Options:

• --session-id, -s: Session ID to visualize
• --style: Visualization style (compact, detailed, minimal)
• --format, -f: Output format (ascii, mermaid)
• --output, -o: Output file
• --analyze/--no-analyze: Include pattern analysis (default: True)

compare

Compare terminal sessions.

termflow compare [OPTIONS]

Options:

• --sessions: Session IDs to compare (e.g., --sessions 1 2)
• --all: Compare all sessions

export

Export a session to file.

termflow export <source> [OPTIONS]

Options:

• --session-id, -s: Session ID to export
• --format: Export format (json, ascii, mermaid)
• --output, -o: Output file (required)

list

List all recorded sessions.

termflow list

show

Show details of a specific session.

termflow show <session_id>

Configuration

Term Flow can be configured using environment variables:

Variable	Description	Default
TERMFLOW_HOME	Configuration directory	~/.termflow
TERMFLOW_DB	Database path	~/.termflow/sessions.db
TERMFLOW_GIT_CACHE	Git cache directory	~/.termflow/git_cache
TERMFLOW_STYLE	Default visualization style	detailed

Architecture

termflow/
├── __main__.py       # CLI entry point
├── core/
│   ├── session.py    # Session data model
│   ├── recorder.py   # Session recording logic
│   └── database.py   # SQLite database management
├── commands/
│   ├── record.py     # Record command
│   ├── visualize.py  # Visualize command
│   ├── compare.py    # Compare command
│   └── export.py     # Export command
├── parsers/
│   ├── git_parser.py      # Git log parsing
│   └── pattern_analyzer.py # Command pattern detection
├── exporters/
│   ├── ascii_generator.py    # ASCII flowchart generation
│   ├── mermaid_generator.py  # Mermaid diagram generation
│   └── graphviz_exporter.py  # Graphviz export
└── utils/
    └── config.py     # Configuration management

Development

Setup

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/term-flow.git
cd term-flow
pip install -e ".[dev]"

Running Tests

pytest tests/ -v

Code Formatting

ruff check .
ruff format .

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

MIT License - see LICENSE file for details.