238 lines
4.9 KiB
Markdown
238 lines
4.9 KiB
Markdown
# 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.
|