TimeTagger

TimeTagger is a self‑hosted, async Python web service that turns raw time entries into actionable insights through an interactive timeline UI. The core idea is lightweight tagging instead of rigid project hierarchies, which simplifies data modeling and keeps the runtime footprint minimal. All data is persisted in a single SQLite database via itemdb, a lightweight key‑value store that abstracts SQL into Pythonic objects. This design choice eliminates the need for a separate database server, making TimeTagger ideal for single‑user or small‑team deployments while still supporting multi‑tenant authentication when credentials are supplied via environment variables or CLI flags.

• Server: Built on uvicorn and the custom async framework asgineer, which offers a non‑blocking, coroutine‑based request pipeline. The API layer is exposed through FastAPI‑style route definitions, and the same runtime handles both REST endpoints and WebSocket connections for real‑time UI updates.
• Client: A hybrid of HTML/CSS/Markdown templates rendered server‑side, with client logic compiled from Python to JavaScript using PScript. This approach keeps the codebase unified while delivering a responsive front‑end that works on both desktop and mobile browsers.
• Data Layer: SQLite via itemdb stores tags, time slices, and user credentials. The library exposes CRUD operations through a simple Python API (timetagger.libapi), which the CLI tool and web UI both consume.
• Testing & CI: Continuous integration runs on GitHub Actions, with coverage reported to Codecov. Documentation is hosted on ReadTheDocs and automatically built alongside the CI pipeline.

• Tag‑Based Time Entry: Users can start/stop timers, assign tags on the fly, and edit entries post‑facto.
• Reporting: Export to CSV or PDF with customizable date ranges, and embed billing data directly into PDFs for invoicing.
• Target Tracking: Set daily/weekly/monthly goals and receive visual progress indicators on the timeline.
• Pomodoro Integration: An experimental Pomodoro timer that can be toggled per session.
• Web API: Exposes endpoints for creating, querying, and deleting entries; supports authentication via a simple credentials header.
• CLI Tool: timetagger_cli allows developers to script time tracking from the terminal, enabling integration into CI pipelines or custom scripts.

TimeTagger ships with pre‑built Docker images on GitHub Container Registry. Two Compose files are provided: one that runs the container as root for quick demos, and a non‑root variant that maps to UID 1000 for production use. The container exposes only the HTTP port, and all configuration (credentials, database path, etc.) is driven by environment variables. Because the service uses SQLite, scaling horizontally requires a shared filesystem or an external database layer; however, for most individual use cases the single‑node deployment suffices. The async nature of the stack allows it to handle many concurrent WebSocket connections with minimal overhead.

• Plugins: While no formal plugin system exists yet, the open‑source codebase allows developers to fork and extend asgineer routes or inject custom PScript modules.
• Webhooks: The API can be wrapped with a lightweight webhook listener to push events (e.g., new entry created) to external services like Slack or GitHub.
• Customization: The front‑end is templated; swapping CSS frameworks or adding custom JavaScript hooks is straightforward.
• Third‑Party Extensions: A VS Code extension (TimeTagger_VSCodeExtension) demonstrates how developers can tap into the API from IDEs.

The library is published on PyPI (timetagger), and its dependencies are minimal (Python ≥3.6, uvicorn, itemdb). Documentation is comprehensive and hosted on ReadTheDocs, covering installation, API usage, deployment scenarios, and advanced configuration. Community support is modest but active; issues on GitHub are triaged quickly, and the project encourages contributions through pull requests. The code is organized into clear packages (timetagger.server, timetagger.libapi, etc.), making it approachable for developers familiar with Python web frameworks.

1. Freelancers: Track billable hours by tag, generate PDF invoices on demand, and set daily targets to stay productive.
2. Small Teams: Run a single instance with user credentials; each member can log time, and the admin can aggregate reports across tags.
3. Developer Tooling: Integrate the CLI into build scripts to time CI jobs or local tasks, then push entries to a shared TimeTagger instance.
4. Educational Projects: Use the lightweight stack as a teaching example for async Python, WebSocket UI updates, and PScript compilation.

• Performance: Asynchronous handling via uvicorn + asgineer delivers low latency even under many concurrent users.
• Simplicity: No external database required; a single SQLite file is enough for most workloads.
• Licensing: MIT‑licensed, allowing unrestricted use in commercial products.
• Extensibility: Unified Python codebase for both server and client makes it easy to add features or adapt the UI.
• Privacy‑First: No third‑party analytics, cookie banners, or external dependencies beyond the core stack.

Overall,