150 lines
4.2 KiB
Markdown
150 lines
4.2 KiB
Markdown
# DevTrace
|
|
|
|
|
|
|
|
|
|
|
|
A CLI tool that automatically snapshots and indexes your entire development workflow in real-time, tracking file changes, terminal commands, git operations, and errors into a local searchable database with natural language query capabilities.
|
|
|
|
## Features
|
|
|
|
- **Real-time File Monitoring**: Track file creations, modifications, deletions, and moves
|
|
- **Command Capture**: Log all terminal commands executed during development sessions
|
|
- **Git Operation Tracking**: Monitor commits, branches, merges, pushes, and pulls
|
|
- **Semantic Search**: Search your workflow using natural language queries
|
|
- **Timeline View**: Visualize your development session as an interactive timeline
|
|
- **Export Capabilities**: Export session data to JSON for external analysis
|
|
|
|
## Installation
|
|
|
|
### From Source
|
|
|
|
```bash
|
|
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/devtrace.git
|
|
cd devtrace
|
|
pip install -e .
|
|
```
|
|
|
|
### Development Installation
|
|
|
|
```bash
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
1. **Initialize DevTrace**:
|
|
```bash
|
|
devtrace init
|
|
```
|
|
|
|
2. **Start a monitoring session**:
|
|
```bash
|
|
devtrace start --project "My Project"
|
|
```
|
|
|
|
3. **View session timeline**:
|
|
```bash
|
|
devtrace timeline 1
|
|
```
|
|
|
|
4. **Search your workflow**:
|
|
```bash
|
|
devtrace search "modified Python files"
|
|
```
|
|
|
|
5. **Ask natural language questions**:
|
|
```bash
|
|
devtrace ask 1 "What commands did I run?"
|
|
```
|
|
|
|
## Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `devtrace init` | Initialize DevTrace database |
|
|
| `devtrace start` | Start a new monitoring session |
|
|
| `devtrace stop` | Stop a monitoring session |
|
|
| `devtrace timeline` | View session timeline |
|
|
| `devtrace search` | Search workflow history |
|
|
| `devtrace ask` | Ask natural language questions |
|
|
| `devtrace sessions` | List all sessions |
|
|
| `devtrace events` | Show events by type |
|
|
| `devtrace export` | Export session to JSON |
|
|
| `devtrace status` | Show DevTrace statistics |
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `DEVTRACE_DIR` | Base directory for DevTrace data | `~/.devtrace` |
|
|
| `DEVTRACE_DB` | SQLite database path | Auto-generated |
|
|
| `DEVTRACE_EMBEDDING_MODEL` | Sentence-transformers model | `all-MiniLM-L6-v2` |
|
|
| `DEVTRACE_WATCH_PATTERNS` | File patterns to watch | `*.py,*.js,*.ts,*.html,*.css` |
|
|
|
|
### Configuration File
|
|
|
|
Create a `.devtracerc` file in your project root:
|
|
|
|
```ini
|
|
[devtrace]
|
|
db_path = /path/to/devtrace.db
|
|
watch_patterns = *.py,*.js,*.ts,*.html,*.css,*.md
|
|
ignored_patterns = __pycache__,.git,node_modules,.venv
|
|
embedding_model = all-MiniLM-L6-v2
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
devtrace/
|
|
├── src/
|
|
│ ├── main.py # Entry point
|
|
│ ├── cli.py # Click CLI commands
|
|
│ ├── monitor/ # Monitoring modules
|
|
│ │ ├── filesystem.py # File monitoring
|
|
│ │ ├── commands.py # Command capture
|
|
│ │ └── git.py # Git tracking
|
|
│ ├── storage/ # Data persistence
|
|
│ │ ├── database.py # SQLite operations
|
|
│ │ └── models.py # Data models
|
|
│ ├── search/ # Search functionality
|
|
│ │ ├── embeddings.py # Embedding management
|
|
│ │ ├── semantic.py # Semantic search
|
|
│ │ └── query.py # Query engine
|
|
│ └── ui/ # User interface
|
|
│ ├── timeline.py # Timeline view
|
|
│ └── display.py # Display utilities
|
|
├── tests/ # Unit tests
|
|
└── requirements.txt # Dependencies
|
|
```
|
|
|
|
## Testing
|
|
|
|
Run the test suite:
|
|
|
|
```bash
|
|
# Run all tests
|
|
pytest tests/ -v
|
|
|
|
# Run with coverage
|
|
pytest tests/ --cov=src
|
|
|
|
# Run specific test file
|
|
pytest tests/test_storage.py -v
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch: `git checkout -b feature/new-feature`
|
|
3. Make your changes and add tests
|
|
4. Run tests: `pytest tests/ -v`
|
|
5. Submit a pull request
|
|
|
|
## License
|
|
|
|
MIT License - see LICENSE file for details.
|