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
- 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.jsonCargo.tomlpyproject.toml/requirements.txtgo.modpom.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]
- CLI: A thin client that sends commands to the daemon. It exits immediately, keeping your shell responsive.
- 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.
- 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/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
-
Start the Daemon
tempo start -
Initialize a Project Navigate to your project folder and tell Tempo to track it.
cd ~/my-cool-project tempo init "My Cool Project"
-
Start Tracking
tempo session start
Tempo will confirm that tracking has started for "My Cool Project".
-
Check Status
tempo status -
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.
- Fork the repository.
- Create a feature branch (
git checkout -b feature/amazing-feature). - Commit your changes.
- Push to the branch.
- 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
maintriggers 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.
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.