Tempo

Simple, Fast, and Privacy-Focused Time Tracking for Developers

Tempo is a lightweight, terminal-based time tracking tool designed specifically for developers. It automatically detects your project context, tracks time with precision, and stores everything locally. No cloud services, no subscriptions, just a fast binary that gets out of your way.

📖 Table of Contents

• Why Tempo?
• Features
• Architecture
• Installation
• Quick Start
• Usage Guide
  • Session Management
  • Project Management
  • Reporting
  • Interactive UI
• Configuration
• Troubleshooting
• Contributing
• License

🚀 Why Tempo?

• Zero Friction: Start tracking in seconds. Tempo infers your project from your current directory.
• Local & Private: Your data lives on your machine in a standard SQLite database. You own it.
• Resource Efficient: The background daemon is written in Rust, consuming negligible CPU and memory (< 5MB).
• Developer Native: Integrates with your existing workflow. Detects Git, Node, Rust, Python, and Go projects automatically.
• Terminal First: Includes a beautiful TUI dashboard and interactive timer for those who live in the terminal.

✨ Features

🧠 Smart Context Detection

Tempo automatically recognizes project roots by looking for common markers:

• .git/
• package.json
• Cargo.toml
• pyproject.toml / requirements.txt
• go.mod
• pom.xml

⏱️ Intelligent Session Management

• Auto-Resume: Pick up exactly where you left off.
• Idle Detection: Automatically pauses tracking when you step away (configurable).
• Concurrent Projects: Switch contexts instantly without losing data.

📊 Powerful Reporting

Generate detailed reports to analyze your productivity or for billing purposes:

• Formats: ASCII tables, CSV, JSON.
• Filters: Date ranges, specific projects, or tags.
• Aggregation: View daily, weekly, or project-based totals.

🖥️ Interactive Dashboard

A full-featured Terminal User Interface (TUI) offering:

• Real-time status monitoring.
• Visual project switcher.
• Activity timeline and statistics.
• Keyboard-driven navigation.

🏗️ Architecture

Tempo follows a Client-Daemon architecture to ensure reliability and speed.

graph LR
    CLI[Tempo CLI] -- Unix Socket --> Daemon[Tempo Daemon]
    Daemon -- Reads/Writes --> DB[(SQLite DB)]
    Daemon -- Monitors --> System[System Activity]

1. CLI: A thin client that sends commands to the daemon. It exits immediately, keeping your shell responsive.
2. Daemon: A background process that manages state, handles database I/O, and monitors system idle time. It ensures time is tracked accurately even if you close your terminal.
3. Storage: All data is persisted in a local SQLite database at ~/.tempo/data.db.

📥 Installation

Option 1: Python Package (Recommended)

The easiest way to install Tempo is via pip or uv. The Python package automatically installs the Rust binary for your platform.

# Fast installation with uv
uv add tempo-tracker-cli

# Or using standard pip
pip install tempo-tracker-cli

Option 2: Rust / Cargo

If you have a Rust toolchain installed, you can install directly from crates.io or build from source.

# Install from crates.io
cargo install tempo-cli

# Or build from source
git clone https://github.com/own-path/tempo.git
cd tempo
cargo build --release
cargo install --path .

Package Information

Tempo is distributed as two packages:

• Python Package: tempo-tracker-cli - Provides easy installation and automatically manages the Rust binary
• Rust Package: tempo-cli - The core application binary

Both packages install the same tempo command-line tool. Choose Python for convenience or Rust for building from source.

System Requirements

• OS: macOS, Linux, or Windows (WSL recommended)
• Terminal: A terminal with TrueColor support (e.g., iTerm2, Alacritty, Ghostty) and a Nerd Font installed is recommended for the best TUI experience

⚡ Quick Start

1. Start the Daemon

   tempo start
   

2. Initialize a Project Navigate to your project folder and tell Tempo to track it.

   cd ~/my-cool-project
   tempo init "My Cool Project"
   

3. Start Tracking

   tempo session start
   

   Tempo will confirm that tracking has started for "My Cool Project".

4. Check Status

   tempo status
   

5. View the Dashboard

   tempo dashboard
   

📖 Usage Guide

Session Management

Project Management

Reporting

Generate reports to visualize your time usage.

# Standard ASCII report
tempo report

# Export to CSV for Excel/Numbers
tempo report --format csv > timesheet.csv

# Filter by date
tempo report --from 2024-01-01 --to 2024-01-31

# Filter by project
tempo report --project "My Cool Project"

Interactive UI

• tempo dashboard: The main command center. View active sessions, switch projects, and see daily stats.
• tempo timer: A focused, full-screen timer view. Great for keeping on a secondary monitor.
• tempo history: An interactive browser for your session history.

⚙️ Configuration

Tempo is highly configurable. Settings are stored in ~/.tempo/config.toml.

You can view and modify settings via the CLI:

# View current config
tempo config show

# Set a value
tempo config set idle_timeout_minutes 10

Available Options

🔧 Troubleshooting

Daemon Not Starting

If tempo start fails, check if a stale PID file exists:

rm ~/.tempo/daemon.pid
tempo start

"Connection Refused"

This usually means the daemon isn't running. Start it with:

tempo start

Missing Icons in TUI

If you see boxes [] or ? instead of icons, ensure you are using a Nerd Font in your terminal emulator.

🤝 Contributing

We welcome contributions! Whether it's bug reports, feature requests, or code, your help is appreciated.

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes.
4. Push to the branch.
5. Open a Pull Request.

See CONTRIBUTING.md for detailed guidelines.

Release Process

Releases are fully automated via release-plz:

• Version Management: Automated PRs are created for version bumps based on conventional commits
• Dual Publishing: Merging to main triggers simultaneous publication to both crates.io and PyPI
• Synchronized Versions: Both packages maintain version parity automatically

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.