Skip to main content

Tempo

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

PyPI Crates.io License: MIT Downloads

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?

  • 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

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/vibe.git
cd vibe
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

Command Description
tempo session start Start tracking time for the current project.
tempo session stop Stop the current session.
tempo session pause Pause the current session (useful for breaks).
tempo session resume Resume a paused session.
tempo session current Display details of the active session.
tempo session list Show a history of recent sessions.
tempo session edit <id> Modify a past session (e.g., fix start/end times).
tempo session delete <id> Permanently remove a session.

Project Management

Command Description
tempo init "<Name>" Initialize tracking for the current directory.
tempo list List all tracked projects.
tempo project archive <id> Archive a project (hides it from default lists).
tempo project update-path Update the path if you moved the project folder.

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

Key Type Default Description
idle_timeout_minutes Number 30 Minutes of inactivity before auto-pausing.
auto_pause_enabled Boolean true Whether to enable auto-pause functionality.
default_context String "terminal" Default tag for sessions (terminal, ide, manual).
max_session_hours Number 48 Safety limit to auto-stop extremely long sessions.
backup_enabled Boolean true Enable automatic database backups.
log_level String "info" Log verbosity (error, warn, info, debug).

🔧 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.


Built with ❤️ by Developers, for Developers.

Metadata

Release files for tempo-tracker-cli 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tempo-tracker-cli 0.3.1
File Size Uploaded Provenance Actions
tempo_tracker_cli-0.3.1.tar.gz 13.6 kB With provenance Details for tempo_tracker_cli-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tempo-tracker-cli 0.3.1
File Interpreter ABI Platform Actions
tempo_tracker_cli-0.3.1-py3-none-any.whl Python 3 none any Details for tempo_tracker_cli-0.3.1-py3-none-any.whl

Total release size: 22.5 kB

Release files / tempo_tracker_cli-0.3.1.tar.gz

Download URL tempo_tracker_cli-0.3.1.tar.gz
Size 13.6 kB
Tags Source
SHA-256 checksum
How to use checksums
dda5d6096577a7428ca0011273c12bea48a13cdd5a3a1e7f7d7b5d2d14d8bdbd
BLAKE2b-256 checksum
How to use checksums
69731a44da07bb26e1ccc9465300321bc90c7b053d6707a8603d734000dc1004
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2025.

Transparency log

Release files / tempo_tracker_cli-0.3.1-py3-none-any.whl

Download URL tempo_tracker_cli-0.3.1-py3-none-any.whl
Size 8.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3de9c4982ad9960878c56e063c4c2930907e43171542e0f4b3609cbb8ea7a421
BLAKE2b-256 checksum
How to use checksums
5c22cf500e67600db951f681b5591c3aeeca16bdde919a8c82f2cf68a277fe84
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2025.

Transparency log

Security for tempo-tracker-cli 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tempo_tracker_cli-0.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2025.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page