# 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

```bash
pip install termflow
```

Or from source:

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

## Quick Start

### Record a Session

```bash
# 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

```bash
termflow list
```

### Visualize a Session

```bash
# 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

```bash
# Visualize current git repository
termflow visualize git

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

### Compare Sessions

```bash
# Compare two sessions
termflow compare --sessions 1 2

# Compare all sessions
termflow compare --all
```

### Export a Session

```bash
# 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.

```bash
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.

```bash
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.

```bash
termflow compare [OPTIONS]
```

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

### export

Export a session to file.

```bash
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.

```bash
termflow list
```

### show

Show details of a specific session.

```bash
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

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

### Running Tests

```bash
pytest tests/ -v
```

### Code Formatting

```bash
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.