timing-cli 0.1.0__tar.gz

timing_cli-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+
+# uv
+uv.lock
+
+# Claude Code
+.claude
+
+# Dolt database files (added by bd init)
+.dolt/
+*.db
+
+# Beads JSONL export is local; Dolt is the source of truth.
+.beads/issues.jsonl
+
+# Beads runtime artifacts (run state, metrics)
+.beads/runs/
+.beads/export-state.json
+
+# Session-close runner artifacts
+.session-close-state.json
+.session-close.lock
+
+# Beads / Dolt files (added by bd init)
+.beads-credential-key
+.beads/proxieddb/

timing_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial scaffold of `timing-cli`.
+- Read-only access to the local Timing.app SQLite database (`db.py`).
+- Rule-based classification of app usage onto projects (`rules.py`).
+- Aggregation of app usage into gap-merged time-entry suggestions (`analysis.py`).
+- Timing Web API client for pushing time entries (`api.py`).
+- Typer CLI: `info`, `projects`, `usage`, `summary`, `suggest`, `push`, `serve`.
+- FastMCP server exposing local activity and entry creation to agents (`serve.py`).

timing_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Malte Sussdorff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

timing_cli-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: timing-cli
+Version: 0.1.0
+Summary: CLI + MCP server for the Timing.app macOS time tracker - reads the local activity database and generates/pushes time entries via the Timing Web API
+Project-URL: Homepage, https://github.com/sussdorff/timing-cli
+Project-URL: Repository, https://github.com/sussdorff/timing-cli
+Project-URL: Issues, https://github.com/sussdorff/timing-cli/issues
+Project-URL: Changelog, https://github.com/sussdorff/timing-cli/blob/main/CHANGELOG.md
+Author: Malte Sussdorff
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,macos,mcp,productivity,time-tracking,timing
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.23.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.15.0
+Description-Content-Type: text/markdown
+
+# timing-cli
+
+A command-line interface **and MCP server** for [Timing.app](https://timingapp.com/)
+on macOS. Unlike the Timing Web API — which cannot see your locally recorded app
+usage — `timing-cli` reads Timing's **local activity database directly**
+(read-only) and turns real app usage into aggregated time entries, which it can
+then push back to Timing via the Web API.
+
+Because it ships an embedded MCP server, agents (e.g. the Hermes personal agent)
+can query your activity and create entries **without ever copying or exposing
+the raw `SQLite.db`** — the server runs locally, next to the database.
+
+> **Not affiliated with Timing.** Independent tool. It only ever *reads* the
+> local database; all writes go through the official Web API.
+
+## What it does
+
+- **Reads** the local Timing store (`~/Library/Application Support/info.eurocomp.Timing2/SQLite.db`)
+  read-only: automatic app activity, window titles, document paths, projects.
+- **Classifies** unassigned activity onto projects with your own rules (Timing's
+  built-in predicate rules only cover ~15% of activity). It also reuses decoded
+  Timing project predicate rules from the local database when Timing did not
+  already assign a slice.
+- **Aggregates** consecutive same-project slices into clean time blocks
+  (gap-merging + minimum-duration filtering).
+- **Pushes** the resulting suggestions to Timing as real time entries via the
+  Web API (with a safe dry-run default).
+- **Serves** all of this over MCP (`timing serve`) for agents.
+
+## Quickstart
+
+```bash
+# Install (globally, via uv)
+uv tool install timing-cli
+
+# See what's in your local database
+timing info
+
+# Daily project summary and suggested entries (read-only)
+timing summary --date 2026-07-05
+timing suggest --date 2026-07-05
+
+# Push suggestions to Timing (dry-run first, then --yes)
+export TIMING_API_KEY=...    # from https://web.timingapp.com/integrations/tokens
+timing push --date 2026-07-05          # dry-run
+timing push --date 2026-07-05 --yes    # actually create entries
+
+# Run the MCP server (for Hermes / other agents)
+timing serve                                  # stdio
+export TIMING_MCP_TOKEN=...
+timing serve --transport http                 # HTTP on 127.0.0.1:8321
+```
+
+`timing push --yes` resolves every non-unassigned suggestion to a unique Web-API
+project before creating anything. If a project is ambiguous or unmapped, the push
+fails before the first write; add a `[project_mappings]` override. Re-running the
+same push skips matching existing entries unless `--replace` is passed.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `timing info` | Database location, recorded date range, token status |
+| `timing projects [--remote] [--archived]` | List projects (local DB or Web API) |
+| `timing usage [--date/--from/--to] [--project ID]` | Raw automatically tracked app usage |
+| `timing summary [--date/--from/--to]` | Total time per project |
+| `timing suggest [--date/--from/--to]` | Aggregated time-entry suggestions (read-only) |
+| `timing push [--date/--from/--to] [--yes] [--replace]` | Create entries via Web API (dry-run by default) |
+| `timing serve [--transport] [--host] [--port]` | Run the MCP server |
+
+## Daily workflow
+
+```bash
+# 1. Inspect the day without writing anything.
+timing summary --date 2026-07-05
+timing suggest --date 2026-07-05
+
+# 2. If push projects are unmapped, inspect remote project references.
+export TIMING_API_KEY=...
+timing projects --remote
+
+# 3. Add missing [project_mappings] entries, then dry-run again.
+timing push --date 2026-07-05
+
+# 4. Create entries once the dry-run looks right.
+timing push --date 2026-07-05 --yes
+```
+
+Re-running step 4 for the same day skips matching existing entries. Use
+`--replace` only when you deliberately want Timing's API to replace overlapping
+entries in the target window.
+
+## Configuration
+
+Optional config at `~/.config/timing-cli/config.toml`:
+
+```toml
+# Override the database path if Timing lives elsewhere.
+# db_path = "~/Library/Application Support/info.eurocomp.Timing2/SQLite.db"
+
+api_base_url = "https://web.timingapp.com/api/v1"
+# api_token = "..."   # prefer the TIMING_API_KEY env var instead
+# mcp_http_token = "..."   # prefer the TIMING_MCP_TOKEN env var instead
+
+min_block_seconds = 120    # drop aggregated blocks shorter than this
+gap_merge_seconds = 300    # merge same-project slices split by a gap up to this
+
+# Optional overrides from local Timing projects to Web-API project references.
+# Keys can be a local id ("id:42"), a full title chain, or a leaf title.
+[project_mappings]
+"Client / Polaris" = "/projects/123"
+"id:42" = "/projects/456"
+
+# Classification rules: map unassigned activity onto projects.
+# First match wins. `app`/`bundle_id` are case-insensitive substrings;
+# `title`/`path` are regexes.
+[[rules]]
+project = "Polaris"
+title = "polaris"
+
+[[rules]]
+project = "Cognovis"
+path = "code/mira"
+```
+
+### Cognovis example
+
+This is a real-world shape for Malte's local setup. Fill the Web-API project
+references from `timing projects --remote`; local project ids can be discovered
+with `timing projects`.
+
+```toml
+api_base_url = "https://web.timingapp.com/api/v1"
+min_block_seconds = 120
+gap_merge_seconds = 300
+
+[project_mappings]
+"cognovis Verwaltung" = "/projects/REMOTE_COGNOVIS_VERWALTUNG"
+"]project-open[" = "/projects/REMOTE_PROJECT_OPEN"
+"Home Electronic" = "/projects/REMOTE_HOME_ELECTRONIC"
+
+[[rules]]
+project = "cognovis Verwaltung"
+title = "(timing|collmex|paperless|invoice|rechnung)"
+
+[[rules]]
+project = "cognovis Verwaltung"
+path = "code/(cli-tools|library)"
+
+[[rules]]
+project = "]project-open["
+app = "Mail"
+title = "project-open"
+```
+
+Timing's own project predicates are loaded from the local `Project.predicate`
+column automatically and applied after explicit config rules. Keep local rules
+for repository paths, editor titles, and project-specific conventions that
+Timing itself does not classify well.
+
+## MCP tools
+
+`timing serve` exposes: `list_timing_projects`, `list_app_usage_tool`,
+`daily_project_summary`, `suggest_time_entries`, `create_time_entry` (write),
+`recorded_date_range`.
+
+HTTP transport requires bearer-token authentication via `TIMING_MCP_TOKEN` or
+`mcp_http_token` in the config. Stdio transport remains local and does not require
+an MCP token.
+
+## Release
+
+The repository includes a GitHub Actions release workflow at
+`.github/workflows/release.yml`. Tag pushes run tests and lint only; published
+GitHub releases or manual dispatches build the package and publish to PyPI using
+Trusted Publishing. Configure a PyPI trusted publisher for the repository and
+the `pypi` environment before running the publish job.
+
+## Requirements
+
+- macOS with Timing.app installed
+- Python 3.12+ (installed automatically by `uv tool install`)
+- A Timing Web API token for pushing entries (read-only commands need no token)
+
+## License
+
+MIT

timing_cli-0.1.0/README.md

@@ -0,0 +1,187 @@
+# timing-cli
+
+A command-line interface **and MCP server** for [Timing.app](https://timingapp.com/)
+on macOS. Unlike the Timing Web API — which cannot see your locally recorded app
+usage — `timing-cli` reads Timing's **local activity database directly**
+(read-only) and turns real app usage into aggregated time entries, which it can
+then push back to Timing via the Web API.
+
+Because it ships an embedded MCP server, agents (e.g. the Hermes personal agent)
+can query your activity and create entries **without ever copying or exposing
+the raw `SQLite.db`** — the server runs locally, next to the database.
+
+> **Not affiliated with Timing.** Independent tool. It only ever *reads* the
+> local database; all writes go through the official Web API.
+
+## What it does
+
+- **Reads** the local Timing store (`~/Library/Application Support/info.eurocomp.Timing2/SQLite.db`)
+  read-only: automatic app activity, window titles, document paths, projects.
+- **Classifies** unassigned activity onto projects with your own rules (Timing's
+  built-in predicate rules only cover ~15% of activity). It also reuses decoded
+  Timing project predicate rules from the local database when Timing did not
+  already assign a slice.
+- **Aggregates** consecutive same-project slices into clean time blocks
+  (gap-merging + minimum-duration filtering).
+- **Pushes** the resulting suggestions to Timing as real time entries via the
+  Web API (with a safe dry-run default).
+- **Serves** all of this over MCP (`timing serve`) for agents.
+
+## Quickstart
+
+```bash
+# Install (globally, via uv)
+uv tool install timing-cli
+
+# See what's in your local database
+timing info
+
+# Daily project summary and suggested entries (read-only)
+timing summary --date 2026-07-05
+timing suggest --date 2026-07-05
+
+# Push suggestions to Timing (dry-run first, then --yes)
+export TIMING_API_KEY=...    # from https://web.timingapp.com/integrations/tokens
+timing push --date 2026-07-05          # dry-run
+timing push --date 2026-07-05 --yes    # actually create entries
+
+# Run the MCP server (for Hermes / other agents)
+timing serve                                  # stdio
+export TIMING_MCP_TOKEN=...
+timing serve --transport http                 # HTTP on 127.0.0.1:8321
+```
+
+`timing push --yes` resolves every non-unassigned suggestion to a unique Web-API
+project before creating anything. If a project is ambiguous or unmapped, the push
+fails before the first write; add a `[project_mappings]` override. Re-running the
+same push skips matching existing entries unless `--replace` is passed.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `timing info` | Database location, recorded date range, token status |
+| `timing projects [--remote] [--archived]` | List projects (local DB or Web API) |
+| `timing usage [--date/--from/--to] [--project ID]` | Raw automatically tracked app usage |
+| `timing summary [--date/--from/--to]` | Total time per project |
+| `timing suggest [--date/--from/--to]` | Aggregated time-entry suggestions (read-only) |
+| `timing push [--date/--from/--to] [--yes] [--replace]` | Create entries via Web API (dry-run by default) |
+| `timing serve [--transport] [--host] [--port]` | Run the MCP server |
+
+## Daily workflow
+
+```bash
+# 1. Inspect the day without writing anything.
+timing summary --date 2026-07-05
+timing suggest --date 2026-07-05
+
+# 2. If push projects are unmapped, inspect remote project references.
+export TIMING_API_KEY=...
+timing projects --remote
+
+# 3. Add missing [project_mappings] entries, then dry-run again.
+timing push --date 2026-07-05
+
+# 4. Create entries once the dry-run looks right.
+timing push --date 2026-07-05 --yes
+```
+
+Re-running step 4 for the same day skips matching existing entries. Use
+`--replace` only when you deliberately want Timing's API to replace overlapping
+entries in the target window.
+
+## Configuration
+
+Optional config at `~/.config/timing-cli/config.toml`:
+
+```toml
+# Override the database path if Timing lives elsewhere.
+# db_path = "~/Library/Application Support/info.eurocomp.Timing2/SQLite.db"
+
+api_base_url = "https://web.timingapp.com/api/v1"
+# api_token = "..."   # prefer the TIMING_API_KEY env var instead
+# mcp_http_token = "..."   # prefer the TIMING_MCP_TOKEN env var instead
+
+min_block_seconds = 120    # drop aggregated blocks shorter than this
+gap_merge_seconds = 300    # merge same-project slices split by a gap up to this
+
+# Optional overrides from local Timing projects to Web-API project references.
+# Keys can be a local id ("id:42"), a full title chain, or a leaf title.
+[project_mappings]
+"Client / Polaris" = "/projects/123"
+"id:42" = "/projects/456"
+
+# Classification rules: map unassigned activity onto projects.
+# First match wins. `app`/`bundle_id` are case-insensitive substrings;
+# `title`/`path` are regexes.
+[[rules]]
+project = "Polaris"
+title = "polaris"
+
+[[rules]]
+project = "Cognovis"
+path = "code/mira"
+```
+
+### Cognovis example
+
+This is a real-world shape for Malte's local setup. Fill the Web-API project
+references from `timing projects --remote`; local project ids can be discovered
+with `timing projects`.
+
+```toml
+api_base_url = "https://web.timingapp.com/api/v1"
+min_block_seconds = 120
+gap_merge_seconds = 300
+
+[project_mappings]
+"cognovis Verwaltung" = "/projects/REMOTE_COGNOVIS_VERWALTUNG"
+"]project-open[" = "/projects/REMOTE_PROJECT_OPEN"
+"Home Electronic" = "/projects/REMOTE_HOME_ELECTRONIC"
+
+[[rules]]
+project = "cognovis Verwaltung"
+title = "(timing|collmex|paperless|invoice|rechnung)"
+
+[[rules]]
+project = "cognovis Verwaltung"
+path = "code/(cli-tools|library)"
+
+[[rules]]
+project = "]project-open["
+app = "Mail"
+title = "project-open"
+```
+
+Timing's own project predicates are loaded from the local `Project.predicate`
+column automatically and applied after explicit config rules. Keep local rules
+for repository paths, editor titles, and project-specific conventions that
+Timing itself does not classify well.
+
+## MCP tools
+
+`timing serve` exposes: `list_timing_projects`, `list_app_usage_tool`,
+`daily_project_summary`, `suggest_time_entries`, `create_time_entry` (write),
+`recorded_date_range`.
+
+HTTP transport requires bearer-token authentication via `TIMING_MCP_TOKEN` or
+`mcp_http_token` in the config. Stdio transport remains local and does not require
+an MCP token.
+
+## Release
+
+The repository includes a GitHub Actions release workflow at
+`.github/workflows/release.yml`. Tag pushes run tests and lint only; published
+GitHub releases or manual dispatches build the package and publish to PyPI using
+Trusted Publishing. Configure a PyPI trusted publisher for the repository and
+the `pypi` environment before running the publish job.
+
+## Requirements
+
+- macOS with Timing.app installed
+- Python 3.12+ (installed automatically by `uv tool install`)
+- A Timing Web API token for pushing entries (read-only commands need no token)
+
+## License
+
+MIT

timing_cli-0.1.0/cliff.toml

@@ -0,0 +1,51 @@
+[changelog]
+header = """
+# Changelog
+
+"""
+body = """
+{% if version %}
+## [{{ version }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+{% else %}
+## [Unreleased]
+{% endif %}
+
+{% for group, commits in commits | group_by(attribute="group") %}
+### {{ group }}
+{% for commit in commits %}
+- {% if commit.scope %}**{{ commit.scope }}:** {% endif %}{{ commit.message | upper_first }}
+{% endfor %}
+{% endfor %}
+
+"""
+trim = true
+
+[git]
+conventional_commits = true
+filter_unconventional = false
+split_commits = false
+protect_breaking_commits = true
+filter_commits = true
+tag_pattern = "^(?:v)?(?:\\d{4}\\.\\d{1,2}\\.\\d{1,2}(?:\\.\\d+)?|\\d+\\.\\d+\\.\\d+)$"
+skip_tags = ""
+ignore_tags = ""
+topo_order = false
+sort_commits = "oldest"
+commit_preprocessors = [
+    { pattern = "^Merge .*", replace = "" },
+]
+commit_parsers = [
+    { message = "^feat", group = "Added" },
+    { message = "^fix", group = "Fixed" },
+    { message = "^perf", group = "Changed" },
+    { message = "^refactor", group = "Changed" },
+    { message = "^docs", group = "Documentation" },
+    { message = "^test", group = "Tests" },
+    { message = "^build", group = "Build" },
+    { message = "^ci", group = "Build" },
+    { message = "^chore", group = "Changed" },
+    { message = "^revert", group = "Changed" },
+    { message = "^bd sync:", skip = true },
+    { message = "^bd:", skip = true },
+    { message = ".*", group = "Changed" },
+]

timing_cli-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "timing-cli"
+version = "0.1.0"
+description = "CLI + MCP server for the Timing.app macOS time tracker - reads the local activity database and generates/pushes time entries via the Timing Web API"
+authors = [
+    { name = "Malte Sussdorff" },
+]
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["timing", "time-tracking", "cli", "mcp", "macos", "productivity"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: MacOS :: MacOS X",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.15.0",
+    "rich>=13.0.0",
+    "fastmcp>=2.0",
+    "mcp>=1.23.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+
+[project.scripts]
+timing = "timing_cli.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/sussdorff/timing-cli"
+Repository = "https://github.com/sussdorff/timing-cli"
+Issues = "https://github.com/sussdorff/timing-cli/issues"
+Changelog = "https://github.com/sussdorff/timing-cli/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["timing_cli"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/timing_cli",
+    "/README.md",
+    "/CHANGELOG.md",
+    "/LICENSE",
+    "/cliff.toml",
+]
+
+[dependency-groups]
+dev = [
+    "git-cliff>=2.12.0",
+    "pytest>=8.0.0",
+    "pytest-cov>=6.0.0",
+    "ruff>=0.8.0",
+    "bandit>=1.8.0",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "C4"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"

timing_cli-0.1.0/timing_cli/__init__.py

@@ -0,0 +1,3 @@
+"""timing-cli: read the local Timing.app database and generate/push time entries."""
+
+__version__ = "0.1.0"