CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Selfspy is a comprehensive activity monitoring suite with implementations in multiple programming languages. It continuously monitors:

Keystrokes (encrypted for security)
Mouse movements and clicks
Active window titles and processes
Activity periods

This is a multi-language project with implementations in Python (primary), Rust, Elixir/Phoenix, Objective-C, Nim, Crystal, Zig, and more. The Python implementation is the most mature and feature-complete.

Project Structure

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
├── [other langs]/    # Additional language implementations
├── shared/           # Shared resources and scripts
├── tools/            # Development tools
└── dev               # Multi-language development helper script

Multi-Language Development

Use the

./dev

helper script to work with different implementations:

# Work with Python (most mature implementation)
./dev python uv run selfspy start
./dev python uv run pytest

# Work with Rust implementation
./dev rust cargo build --release
./dev rust cargo run --bin selfspy-gui

# Work with Elixir/Phoenix web interface
./dev elixir mix phx.server
./dev elixir mix test

# Work with other implementations
./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

# Language-agnostic commands
./dev test                          # Run all tests
./dev build                         # Build all implementations

Note: You are currently on the

elixir-phoenix-implementation

branch, which indicates active development on the Elixir/Phoenix web interface implementation.

Python Implementation Commands

The following commands are specific to the Python implementation (located in

python/

directory):

Setup and Installation

Option 1: Using uv (recommended for development)

# Install dependencies
uv sync --group dev

# Install with macOS extras for full functionality
uv sync --group dev --extra macos

# Alternative uv installation
uv pip install .

Option 2: Using pip (standard Python)

# Quick automatic installation
python3 install.py

# Manual installation - basic
pip3 install -r requirements.txt
pip3 install -e .

# Manual installation - macOS with full functionality
pip3 install -r requirements-macos.txt
pip3 install -e .

# Development setup
pip3 install -r requirements-dev.txt
pip3 install -e .

Running the Application

With uv (from development environment):

# Start monitoring (will guide through permission setup on macOS)
uv run selfspy start

# Start monitoring with custom data directory
uv run selfspy start --data-dir /path/to/data

# Start monitoring without text logging
uv run selfspy start --no-text

# View enhanced statistics with rich visualizations 🎨
uv run selfviz enhanced

# View activity timeline
uv run selfviz timeline --days 1

# Terminal command analytics 🔧
uv run selfterminal commands --days 7
uv run selfspy terminal sessions --days 30

# Check macOS permissions manually
uv run selfspy check-permissions

Direct commands (after installation):

# Start monitoring
selfspy start

# View statistics
selfstats
selfviz enhanced

# Terminal analytics
selfterminal commands --days 7
selfspy terminal projects --days 30

# Check permissions (macOS)
selfspy check-permissions

Development and Testing

With uv (recommended for development):

# Run tests
uv run pytest

# Run with coverage (default from pytest.ini)
uv run pytest --cov=src

# Run a single test file
uv run pytest tests/test_models.py

# Linting and formatting
uv run black src/ tests/
uv run isort src/ tests/
uv run ruff check src/ tests/
uv run mypy src/

# Pre-commit hooks
uv run pre-commit run --all-files

Direct commands (after pip installation):

# Run tests
pytest

# Linting and formatting
black src/ tests/
isort src/ tests/
ruff check src/ tests/
mypy src/

# Pre-commit hooks
pre-commit run --all-files

Architecture Overview

Core Components

Entry Points (

python/src/cli.py

and
python/src/stats.py
)

Uses Typer for modern CLI interface with Rich output
Main commands:
```
start
```
(monitoring),
```
stats
```
(analysis),
```
check-permissions
```
Handles async event loops and signal handling

Activity Monitor (

python/src/activity_monitor.py

)

Central orchestrator using async patterns
Manages platform-specific trackers (keyboard, mouse, window)
Includes terminal command tracking (background task)
Maintains live dashboard during monitoring
Buffers keystrokes before storage to reduce I/O

Terminal Tracking (

python/src/terminal_tracker.py

and
python/src/terminal_stats.py
)

Monitors shell command history files (bash, zsh, fish)
Tracks commands by working directory and project context
Categorizes commands by type (git, npm, python, etc.)
Detects project types and git branches automatically
Provides rich analytics and visualizations for development workflows

Data Layer

```
python/src/models.py
```
: SQLAlchemy 2.0 models with modern mapped_column syntax
```
python/src/activity_store.py
```
: Database operations with async session management
```
python/src/encryption.py
```
: Handles keystroke encryption using cryptography library

Platform Abstraction (

python/src/platform/

)

```
base.py
```
: Abstract interfaces for cross-platform support
```
darwin.py
```
: macOS-specific implementations using PyObjC
```
fallback.py
```
: Basic implementations for other platforms
Platform detection and graceful degradation

Key Design Patterns

Async/Await: All I/O operations use asyncio for better performance
Dependency Injection: Settings and stores passed to components
Platform Abstraction: Interface-based design allows platform-specific implementations
Encryption by Default: All keystroke data encrypted unless explicitly disabled
Modern Python: Uses type hints, dataclasses, and modern SQLAlchemy patterns

Database Schema

Uses SQLAlchemy 2.0 with declarative base and relationships:

```
Process
```
: Application information with macOS bundle IDs
```
Window
```
: Window metadata including geometry and screen info
```
Keys
```
: Encrypted keystroke data with counts
```
Click
```
: Mouse events with coordinates and movement tracking
```
TerminalSession
```
: Terminal session metadata (shell type, working directory)
```
TerminalCommand
```
: Individual commands with context (git branch, project type, exit codes)

All tables include timestamp mixins and proper indexing for performance.

Configuration (

python/src/config.py

)

Uses Pydantic Settings for type-safe configuration:

Environment variable support with
```
SELFSPY_
```
prefix
Path validation and automatic directory creation
Platform-specific settings for macOS features
Privacy and security controls

macOS Integration

The project has extensive macOS support requiring:

Accessibility permissions for window tracking
Optional Screen Recording permissions for screenshots
PyObjC frameworks for native API access
Bundle ID tracking for better app identification

Use

uv sync --group dev --extra macos

for full macOS functionality.

Security Considerations

All keystroke data encrypted by default using industry-standard cryptography
Configurable exclusions for sensitive applications
Privacy mode available for restricted logging
Local storage only - no network transmission
Secure password handling via keyring integration

Testing and Code Quality

Uses pytest with async support and coverage reporting
Code formatting with Black and import sorting with isort
Type checking with mypy
Linting with ruff
Pre-commit hooks for code quality enforcement

The codebase follows modern Python conventions with comprehensive type hints and documentation.

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Selfspy is a comprehensive activity monitoring suite with implementations in multiple programming languages. It continuously monitors:

Keystrokes (encrypted for security)
Mouse movements and clicks
Active window titles and processes
Activity periods

Project Structure

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
├── [other langs]/    # Additional language implementations
├── shared/           # Shared resources and scripts
├── tools/            # Development tools
└── dev               # Multi-language development helper script

Multi-Language Development

Use the

./dev

helper script to work with different implementations:

# Work with Python (most mature implementation)
./dev python uv run selfspy start
./dev python uv run pytest

# Work with Rust implementation
./dev rust cargo build --release
./dev rust cargo run --bin selfspy-gui

# Work with Elixir/Phoenix web interface
./dev elixir mix phx.server
./dev elixir mix test

# Work with other implementations
./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

# Language-agnostic commands
./dev test                          # Run all tests
./dev build                         # Build all implementations

Note: You are currently on the

elixir-phoenix-implementation

branch, which indicates active development on the Elixir/Phoenix web interface implementation.

Python Implementation Commands

The following commands are specific to the Python implementation (located in

python/

directory):

Setup and Installation

Option 1: Using uv (recommended for development)

# Install dependencies
uv sync --group dev

# Install with macOS extras for full functionality
uv sync --group dev --extra macos

# Alternative uv installation
uv pip install .

Option 2: Using pip (standard Python)

# Quick automatic installation
python3 install.py

# Manual installation - basic
pip3 install -r requirements.txt
pip3 install -e .

# Manual installation - macOS with full functionality
pip3 install -r requirements-macos.txt
pip3 install -e .

# Development setup
pip3 install -r requirements-dev.txt
pip3 install -e .

Running the Application

With uv (from development environment):

# Start monitoring (will guide through permission setup on macOS)
uv run selfspy start

# Start monitoring with custom data directory
uv run selfspy start --data-dir /path/to/data

# Start monitoring without text logging
uv run selfspy start --no-text

# View enhanced statistics with rich visualizations 🎨
uv run selfviz enhanced

# View activity timeline
uv run selfviz timeline --days 1

# Terminal command analytics 🔧
uv run selfterminal commands --days 7
uv run selfspy terminal sessions --days 30

# Check macOS permissions manually
uv run selfspy check-permissions

Direct commands (after installation):

# Start monitoring
selfspy start

# View statistics
selfstats
selfviz enhanced

# Terminal analytics
selfterminal commands --days 7
selfspy terminal projects --days 30

# Check permissions (macOS)
selfspy check-permissions

Development and Testing

With uv (recommended for development):

# Run tests
uv run pytest

# Run with coverage (default from pytest.ini)
uv run pytest --cov=src

# Run a single test file
uv run pytest tests/test_models.py

# Linting and formatting
uv run black src/ tests/
uv run isort src/ tests/
uv run ruff check src/ tests/
uv run mypy src/

# Pre-commit hooks
uv run pre-commit run --all-files

Direct commands (after pip installation):

# Run tests
pytest

# Linting and formatting
black src/ tests/
isort src/ tests/
ruff check src/ tests/
mypy src/

# Pre-commit hooks
pre-commit run --all-files

Architecture Overview

Core Components

Entry Points (

python/src/cli.py

and
python/src/stats.py
)

Uses Typer for modern CLI interface with Rich output
Main commands:
```
start
```
(monitoring),
```
stats
```
(analysis),
```
check-permissions
```
Handles async event loops and signal handling

Activity Monitor (

python/src/activity_monitor.py

)

Central orchestrator using async patterns
Manages platform-specific trackers (keyboard, mouse, window)
Includes terminal command tracking (background task)
Maintains live dashboard during monitoring
Buffers keystrokes before storage to reduce I/O

Terminal Tracking (

python/src/terminal_tracker.py

and
python/src/terminal_stats.py
)

Monitors shell command history files (bash, zsh, fish)
Tracks commands by working directory and project context
Categorizes commands by type (git, npm, python, etc.)
Detects project types and git branches automatically
Provides rich analytics and visualizations for development workflows

Data Layer

```
python/src/models.py
```
: SQLAlchemy 2.0 models with modern mapped_column syntax
```
python/src/activity_store.py
```
: Database operations with async session management
```
python/src/encryption.py
```
: Handles keystroke encryption using cryptography library

Platform Abstraction (

python/src/platform/

)

```
base.py
```
: Abstract interfaces for cross-platform support
```
darwin.py
```
: macOS-specific implementations using PyObjC
```
fallback.py
```
: Basic implementations for other platforms
Platform detection and graceful degradation

Key Design Patterns

Async/Await: All I/O operations use asyncio for better performance
Dependency Injection: Settings and stores passed to components
Platform Abstraction: Interface-based design allows platform-specific implementations
Encryption by Default: All keystroke data encrypted unless explicitly disabled
Modern Python: Uses type hints, dataclasses, and modern SQLAlchemy patterns

Database Schema

Uses SQLAlchemy 2.0 with declarative base and relationships:

```
Process
```
: Application information with macOS bundle IDs
```
Window
```
: Window metadata including geometry and screen info
```
Keys
```
: Encrypted keystroke data with counts
```
Click
```
: Mouse events with coordinates and movement tracking
```
TerminalSession
```
: Terminal session metadata (shell type, working directory)
```
TerminalCommand
```
: Individual commands with context (git branch, project type, exit codes)

All tables include timestamp mixins and proper indexing for performance.

Configuration (

python/src/config.py

)

Uses Pydantic Settings for type-safe configuration:

Environment variable support with
```
SELFSPY_
```
prefix
Path validation and automatic directory creation
Platform-specific settings for macOS features
Privacy and security controls

macOS Integration

The project has extensive macOS support requiring:

Accessibility permissions for window tracking
Optional Screen Recording permissions for screenshots
PyObjC frameworks for native API access
Bundle ID tracking for better app identification

Use

uv sync --group dev --extra macos

for full macOS functionality.

Security Considerations

All keystroke data encrypted by default using industry-standard cryptography
Configurable exclusions for sensitive applications
Privacy mode available for restricted logging
Local storage only - no network transmission
Secure password handling via keyring integration

Testing and Code Quality

Uses pytest with async support and coverage reporting
Code formatting with Black and import sorting with isort
Type checking with mypy
Linting with ruff
Pre-commit hooks for code quality enforcement

The codebase follows modern Python conventions with comprehensive type hints and documentation.

CLAUDE.md

CLAUDE.md

Project Overview

Project Structure

Multi-Language Development

Python Implementation Commands

Setup and Installation

Running the Application

Development and Testing

Architecture Overview

Core Components

Key Design Patterns

Database Schema

Configuration (
`python/src/config.py`
)

macOS Integration

Security Considerations

Testing and Code Quality

Related Skills

Markdown Converter

Nano Banana Pro

1password

CLAUDE.md

Project Overview

Project Structure

Multi-Language Development

Python Implementation Commands

Setup and Installation

Running the Application

Development and Testing

Architecture Overview

Core Components

Key Design Patterns

Database Schema

Configuration (
`python/src/config.py`
)

macOS Integration

Security Considerations

Testing and Code Quality