Development guidance for Selfspy3 multi-language activity monitoring suite
This skill provides comprehensive development guidance for working with the Selfspy3 activity monitoring suite.
Selfspy3 is a multi-language activity monitoring suite that tracks keystrokes (encrypted), mouse movements, window titles, and terminal commands. The Python implementation (in `python/`) is the most mature and feature-complete.
```
selfspy3/
├── python/ # Main Python implementation (most mature)
├── rust/ # Rust implementation with GUI
├── elixir/ # Phoenix web interface
├── objective-c/ # macOS native widgets
├── nim/ # Nim compiled implementation
├── crystal/ # Crystal implementation
├── zig/ # Zig high-performance implementation
├── shared/ # Shared resources and scripts
├── tools/ # Development tools
└── dev # Multi-language development helper script
```
**Check current branch context:**
**Key entry points:**
**Recommended: Using uv (modern Python package manager):**
```bash
./dev python uv sync --group dev
./dev python uv sync --group dev --extra macos
```
**Alternative: Using pip:**
```bash
./dev python python3 install.py
./dev python pip3 install -r requirements.txt
./dev python pip3 install -e .
./dev python pip3 install -r requirements-macos.txt
./dev python pip3 install -r requirements-dev.txt
```
**Start monitoring:**
```bash
./dev python uv run selfspy start
./dev python uv run selfspy start --data-dir /path/to/data
./dev python uv run selfspy start --no-text
./dev python uv run selfspy check-permissions
```
**View statistics and analytics:**
```bash
./dev python uv run selfviz enhanced
./dev python uv run selfviz timeline --days 1
./dev python uv run selfterminal commands --days 7
./dev python uv run selfterminal sessions --days 30
./dev python uv run selfterminal projects --days 30
```
**Run tests:**
```bash
./dev python uv run pytest
./dev python uv run pytest tests/test_models.py
./dev python uv run pytest -v
```
**Code quality checks:**
```bash
./dev python uv run black src/ tests/
./dev python uv run isort src/ tests/
./dev python uv run ruff check src/ tests/
./dev python uv run mypy src/
./dev python uv run pre-commit run --all-files
```
**Rust (with GUI):**
```bash
./dev rust cargo build --release
./dev rust cargo run --bin selfspy-gui
./dev rust cargo test
```
**Elixir/Phoenix (web interface):**
```bash
./dev elixir mix deps.get
./dev elixir mix phx.server
./dev elixir mix test
```
**Other implementations:**
```bash
./dev objective-c make all # macOS widgets
./dev nim nimble build # Nim compiled
./dev crystal shards build # Crystal compiled
./dev zig zig build # Zig performance
```
**Cross-language commands:**
```bash
./dev test # Run all tests across implementations
./dev build # Build all implementations
```
**When reading code:**
**Key components:**
**Database models** (in `models.py`):
**Required permissions:**
**Installation for full macOS support:**
```bash
./dev python uv sync --group dev --extra macos
```
**Features enabled:**
**Built-in protections:**
**Configuration** (via `config.py` and environment variables):
**Adding new tracker:**
1. Create abstract interface in `platform/base.py`
2. Implement in `platform/darwin.py` for macOS
3. Add fallback in `platform/fallback.py`
4. Register in `ActivityMonitor`
5. Add tests in `tests/`
**Adding new CLI command:**
1. Add to `cli.py` using Typer decorators
2. Use Rich for beautiful terminal output
3. Handle async operations properly
4. Add tests and update documentation
**Modifying database schema:**
1. Update models in `models.py` using SQLAlchemy 2.0 syntax
2. Add proper indexes for performance
3. Include timestamp mixins
4. Test migrations with existing data
**Before committing:**
```bash
./dev python uv run pytest
./dev python uv run black src/ tests/
./dev python uv run isort src/ tests/
./dev python uv run ruff check src/ tests/
./dev python uv run mypy src/
./dev python uv run pre-commit run --all-files
```
**Coverage expectations:**
1. **Do not break encryption** - Keystroke data must remain encrypted by default
2. **Respect platform boundaries** - Use abstract interfaces, implement platform-specific code in `platform/` directory
3. **Maintain async patterns** - All I/O should be async, don't block the event loop
4. **Follow SQLAlchemy 2.0 syntax** - Use `mapped_column`, not legacy `Column` API
5. **Type everything** - Comprehensive type hints are required for new code
6. **Test async code properly** - Use pytest-asyncio fixtures and decorators
**Example 1: Start monitoring with custom settings**
```bash
./dev python uv run selfspy start --data-dir ~/my-selfspy-data --log-level DEBUG
```
**Example 2: Analyze terminal activity**
```bash
./dev python uv run selfterminal commands --days 7
./dev python uv run selfterminal sessions --days 30
```
**Example 3: Run quality checks before commit**
```bash
./dev python uv run black src/ tests/ && \
./dev python uv run isort src/ tests/ && \
./dev python uv run ruff check src/ tests/ && \
./dev python uv run mypy src/ && \
./dev python uv run pytest
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/selfspy3-guide/raw