aw-watcher-agent 0.2.0__tar.gz

aw_watcher_agent-0.2.0/.gitignore

@@ -0,0 +1,43 @@
+*.pyc
+__pycache__
+*.egg-info
+.mypy_cache
+.pytest_cache
+.ruff_cache
+
+# Python build artifacts
+build/
+dist/
+
+# Secrets - never commit
+scripts/discord/logs/*
+scripts/*/.env
+scripts/*/.oauth-state
+scripts/*/.tokens.json
+scripts/.env
+*.oauth-state
+*.tokens.json
+# Per-agent identity allowlist written by dotfiles/install.sh. It carries a
+# machine-specific git identity and must never be committed from a checkout
+# whose ~/.config is symlinked into this tree.
+dotfiles/.config/git/allowed-identities.conf
+
+.venv/
+venv/
+.gptme/
+
+# Community plugins index (generated artifact — do not commit snapshots)
+state/community_plugins.json
+docs/community_plugins.json
+
+# Task lock files (runtime state)
+state/locks/
+
+# Session state files (runtime state)
+state/sessions/
+
+# Stale directory from tasks->gptodo rename (PR #171)
+packages/tasks/
+
+# Dashboard build output
+_site/

aw_watcher_agent-0.2.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: aw-watcher-agent
+Version: 0.2.0
+Summary: ActivityWatch watcher for AI coding assistants (gptme, Claude Code, Codex)
+License-Expression: MIT
+Keywords: activitywatch,ai-agents,aw-watcher,gptme,time-tracking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# aw-watcher-agent
+
+An [ActivityWatch](https://activitywatch.net) watcher for **AI coding
+assistants** (gptme, Claude Code, Codex). It logs agent sessions and per-tool
+activity to your **local** aw-server, so AI work shows up in the aw-webui
+Timeline alongside window/AFK data instead of looking like idle time.
+
+**Status:** alpha (`0.2.0`). Session tracking and the Codex log-tailer work and
+are dogfooded against a local aw-server, as is the Claude Code log-tailer. A
+native gptme plugin hook for per-tool events and an aw-webui "AI work" view are
+not built yet.
+
+This is the controller use case behind
+[ActivityWatch/activitywatch#1215](https://github.com/ActivityWatch/activitywatch/issues/1215).
+
+## Design
+
+- **Local-only, privacy-first.** Writes go only to your own aw-server
+  (default `http://127.0.0.1:5600`). No hosted aggregation and no transcripts —
+  only coarse metadata (harness, model, category, tool name, status, counts).
+- **No dependencies.** A small vendored stdlib REST client instead of
+  `aw-client` / `aw-core`, so it is light enough to call from a lifecycle hook.
+- **One clean Timeline block per session.** `emit-start` posts a zero-duration
+  placeholder; `emit-end` deletes it and posts a single event with the full
+  duration plus `outcome`. If the session crashes before `emit-end`, the
+  placeholder still marks that it started.
+- **Never breaks the session it observes.** Errors are reported on stderr and
+  the CLI exits 0, unless you pass `--strict`.
+
+## Install
+
+```bash
+pipx install aw-watcher-agent   # or: pip install aw-watcher-agent / uv tool install aw-watcher-agent
+# latest unreleased master:
+pip install "git+https://github.com/gptme/gptme-contrib#subdirectory=packages/aw-watcher-agent"
+# or, from a gptme-contrib checkout:
+pip install -e packages/aw-watcher-agent
+```
+
+This installs the `aw-watcher-agent` command. You need a running aw-server
+(ActivityWatch's default on port 5600).
+
+## Usage
+
+### Sessions
+
+```bash
+# Create the session bucket (idempotent; emit-start also does this)
+aw-watcher-agent ensure-bucket
+
+# At session start
+aw-watcher-agent emit-start \
+  --harness claude-code --model claude-opus-4-7 \
+  --category code --session-id 8531 --trigger autonomous --workspace myagent
+
+# At session end (reads the saved start state, records duration + outcome)
+aw-watcher-agent emit-end --session-id 8531 --outcome productive
+```
+
+Events land in the bucket `aw-watcher-agent_<hostname>` (type
+`app.agent.session`), which appears in aw-webui automatically.
+
+Session flags (shared by `emit-start`, `emit-end` and `emit-activity`):
+`--harness`, `--model`, `--category`, `--session-id`, `--trigger`,
+`--workspace`, `--hostname` (default: the machine hostname) and `--server`
+(aw-server base URL). `emit-end` additionally takes `--outcome` and
+`--duration` (seconds; used only when no start state was recorded). Values
+passed to `emit-end` override the ones saved at start.
+
+Start state is kept per session id under
+`$XDG_STATE_HOME/aw-watcher-agent/` (default `~/.local/state/aw-watcher-agent/`).
+
+### Claude Code without hooks (log-tailer)
+
+`tail-claude-code` reads the transcripts Claude Code already writes under
+`~/.claude/projects/` (or `$CLAUDE_CONFIG_DIR/projects`) and posts one
+session event per working block, so Claude Code work shows up on the Timeline
+with no harness configuration:
+
+```bash
+aw-watcher-agent tail-claude-code            # every transcript
+aw-watcher-agent tail-claude-code --gap 600  # split blocks on 10 min idle
+```
+
+Only `timestamp`, `sessionId` and `cwd` are read; prompts, replies and tool
+payloads are never touched. A session is split into blocks on idle gaps
+longer than `--gap` (default 15 min), so a session left open overnight is not
+counted as agent time. The trailing block is held back until it has been idle
+for `--gap`, and a per-transcript cursor records each successful post. Overlapping
+invocations skip transcripts already being processed. Cursor writes are atomic;
+retrying a failed later post does not replay the checkpointed prefix. Once blocks
+have been emitted, changing `--gap` for that transcript is rejected rather than
+posting overlapping representations. A digest of the checkpointed event metadata
+also rejects historical inserts, rewrites or truncation that change already emitted
+blocks; it does not silently skip or replay them. Only a missing cursor starts a
+new import: unreadable, corrupt or older count-only cursors fail closed. Preserve
+such a cursor and reconcile the destination events before resetting it, since
+removing it reimports the transcript. A failed transcript is reported on stderr
+without preventing other transcripts from being processed; `--strict` returns
+nonzero after the scan if any failed. This is not transactional exactly-once
+delivery: a crash after the server accepts a post but before its checkpoint can
+still duplicate that last event on retry. Events land in the same session bucket
+as the hooks below, with `harness=claude-code` and `workspace` set to the project
+directory. Use either the tailer or lifecycle hooks for a session, not both.
+
+### Wiring into Claude Code (or any harness with lifecycle hooks)
+
+Point your harness's session-start / session-end hooks (for Claude Code:
+`SessionStart` / `SessionEnd` in `settings.json`) at `emit-start` / `emit-end`,
+passing the same `--session-id` to both. Do not use Claude Code's `Stop` hook for
+`emit-end`: it fires after every response, so the first turn closes the session
+and each later turn posts an empty 0s event. Keep the `SessionEnd` hook
+synchronous (not `async`) so the post finishes before the process exits.
+
+### Per-tool activity
+
+Tool calls go to a sibling bucket, `aw-watcher-agent-activity_<hostname>`
+(type `app.agent.activity`). Adjacent calls with the same tool and status within
+`--pulsetime` seconds (default 5) merge into one Timeline block.
+
+Emit a single tool event yourself, e.g. from a post-tool hook:
+
+```bash
+aw-watcher-agent emit-activity --harness claude-code --session-id 8531 \
+  --tool shell --status success --duration-ms 1200
+```
+
+### Per-tool activity from Codex (log-tailer)
+
+Codex can't host an in-process hook, so `tail-codex` reads its rollout
+transcripts (`~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`), pairs each
+`function_call` with its `function_call_output`, derives a coarse
+`success` / `error` / `completed` status, and emits one activity event per call:
+
+```bash
+# Process the most recent rollout transcript
+aw-watcher-agent tail-codex
+
+# Or a specific transcript, with a custom merge window
+aw-watcher-agent tail-codex --file ~/.codex/sessions/2026/05/29/rollout-...jsonl --pulsetime 5
+```
+
+A cursor per transcript (in the same state directory) records what was already
+emitted, so it is safe to run `tail-codex` repeatedly from a timer or after
+each Codex run.
+
+## Command reference
+
+| Command | Purpose |
+|---------|---------|
+| `ensure-bucket` | Create the session bucket if missing |
+| `emit-start` | Record session start (zero-duration placeholder) |
+| `emit-end` | Replace the placeholder with one event carrying duration + `--outcome` |
+| `emit-activity` | Record one tool-activity heartbeat (`--tool` required) |
+| `tail-codex` | Emit per-tool activity from a Codex rollout transcript |
+| `tail-claude-code` | Emit session working blocks from Claude Code transcripts (no hooks) |
+
+Global flag: `--strict` (exit non-zero on errors). Run
+`aw-watcher-agent <command> --help` for all options.
+
+## Related
+
+- [gptme-sessions](../gptme-sessions/README.md) — session tracking and
+  analytics on the agent side (this watcher puts the same sessions on your
+  ActivityWatch timeline).
+- [gptme-activity-summary](../gptme-activity-summary/README.md) — summarizes
+  agent activity, including ActivityWatch data.

aw_watcher_agent-0.2.0/README.md

@@ -0,0 +1,167 @@
+# aw-watcher-agent
+
+An [ActivityWatch](https://activitywatch.net) watcher for **AI coding
+assistants** (gptme, Claude Code, Codex). It logs agent sessions and per-tool
+activity to your **local** aw-server, so AI work shows up in the aw-webui
+Timeline alongside window/AFK data instead of looking like idle time.
+
+**Status:** alpha (`0.2.0`). Session tracking and the Codex log-tailer work and
+are dogfooded against a local aw-server, as is the Claude Code log-tailer. A
+native gptme plugin hook for per-tool events and an aw-webui "AI work" view are
+not built yet.
+
+This is the controller use case behind
+[ActivityWatch/activitywatch#1215](https://github.com/ActivityWatch/activitywatch/issues/1215).
+
+## Design
+
+- **Local-only, privacy-first.** Writes go only to your own aw-server
+  (default `http://127.0.0.1:5600`). No hosted aggregation and no transcripts —
+  only coarse metadata (harness, model, category, tool name, status, counts).
+- **No dependencies.** A small vendored stdlib REST client instead of
+  `aw-client` / `aw-core`, so it is light enough to call from a lifecycle hook.
+- **One clean Timeline block per session.** `emit-start` posts a zero-duration
+  placeholder; `emit-end` deletes it and posts a single event with the full
+  duration plus `outcome`. If the session crashes before `emit-end`, the
+  placeholder still marks that it started.
+- **Never breaks the session it observes.** Errors are reported on stderr and
+  the CLI exits 0, unless you pass `--strict`.
+
+## Install
+
+```bash
+pipx install aw-watcher-agent   # or: pip install aw-watcher-agent / uv tool install aw-watcher-agent
+# latest unreleased master:
+pip install "git+https://github.com/gptme/gptme-contrib#subdirectory=packages/aw-watcher-agent"
+# or, from a gptme-contrib checkout:
+pip install -e packages/aw-watcher-agent
+```
+
+This installs the `aw-watcher-agent` command. You need a running aw-server
+(ActivityWatch's default on port 5600).
+
+## Usage
+
+### Sessions
+
+```bash
+# Create the session bucket (idempotent; emit-start also does this)
+aw-watcher-agent ensure-bucket
+
+# At session start
+aw-watcher-agent emit-start \
+  --harness claude-code --model claude-opus-4-7 \
+  --category code --session-id 8531 --trigger autonomous --workspace myagent
+
+# At session end (reads the saved start state, records duration + outcome)
+aw-watcher-agent emit-end --session-id 8531 --outcome productive
+```
+
+Events land in the bucket `aw-watcher-agent_<hostname>` (type
+`app.agent.session`), which appears in aw-webui automatically.
+
+Session flags (shared by `emit-start`, `emit-end` and `emit-activity`):
+`--harness`, `--model`, `--category`, `--session-id`, `--trigger`,
+`--workspace`, `--hostname` (default: the machine hostname) and `--server`
+(aw-server base URL). `emit-end` additionally takes `--outcome` and
+`--duration` (seconds; used only when no start state was recorded). Values
+passed to `emit-end` override the ones saved at start.
+
+Start state is kept per session id under
+`$XDG_STATE_HOME/aw-watcher-agent/` (default `~/.local/state/aw-watcher-agent/`).
+
+### Claude Code without hooks (log-tailer)
+
+`tail-claude-code` reads the transcripts Claude Code already writes under
+`~/.claude/projects/` (or `$CLAUDE_CONFIG_DIR/projects`) and posts one
+session event per working block, so Claude Code work shows up on the Timeline
+with no harness configuration:
+
+```bash
+aw-watcher-agent tail-claude-code            # every transcript
+aw-watcher-agent tail-claude-code --gap 600  # split blocks on 10 min idle
+```
+
+Only `timestamp`, `sessionId` and `cwd` are read; prompts, replies and tool
+payloads are never touched. A session is split into blocks on idle gaps
+longer than `--gap` (default 15 min), so a session left open overnight is not
+counted as agent time. The trailing block is held back until it has been idle
+for `--gap`, and a per-transcript cursor records each successful post. Overlapping
+invocations skip transcripts already being processed. Cursor writes are atomic;
+retrying a failed later post does not replay the checkpointed prefix. Once blocks
+have been emitted, changing `--gap` for that transcript is rejected rather than
+posting overlapping representations. A digest of the checkpointed event metadata
+also rejects historical inserts, rewrites or truncation that change already emitted
+blocks; it does not silently skip or replay them. Only a missing cursor starts a
+new import: unreadable, corrupt or older count-only cursors fail closed. Preserve
+such a cursor and reconcile the destination events before resetting it, since
+removing it reimports the transcript. A failed transcript is reported on stderr
+without preventing other transcripts from being processed; `--strict` returns
+nonzero after the scan if any failed. This is not transactional exactly-once
+delivery: a crash after the server accepts a post but before its checkpoint can
+still duplicate that last event on retry. Events land in the same session bucket
+as the hooks below, with `harness=claude-code` and `workspace` set to the project
+directory. Use either the tailer or lifecycle hooks for a session, not both.
+
+### Wiring into Claude Code (or any harness with lifecycle hooks)
+
+Point your harness's session-start / session-end hooks (for Claude Code:
+`SessionStart` / `SessionEnd` in `settings.json`) at `emit-start` / `emit-end`,
+passing the same `--session-id` to both. Do not use Claude Code's `Stop` hook for
+`emit-end`: it fires after every response, so the first turn closes the session
+and each later turn posts an empty 0s event. Keep the `SessionEnd` hook
+synchronous (not `async`) so the post finishes before the process exits.
+
+### Per-tool activity
+
+Tool calls go to a sibling bucket, `aw-watcher-agent-activity_<hostname>`
+(type `app.agent.activity`). Adjacent calls with the same tool and status within
+`--pulsetime` seconds (default 5) merge into one Timeline block.
+
+Emit a single tool event yourself, e.g. from a post-tool hook:
+
+```bash
+aw-watcher-agent emit-activity --harness claude-code --session-id 8531 \
+  --tool shell --status success --duration-ms 1200
+```
+
+### Per-tool activity from Codex (log-tailer)
+
+Codex can't host an in-process hook, so `tail-codex` reads its rollout
+transcripts (`~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`), pairs each
+`function_call` with its `function_call_output`, derives a coarse
+`success` / `error` / `completed` status, and emits one activity event per call:
+
+```bash
+# Process the most recent rollout transcript
+aw-watcher-agent tail-codex
+
+# Or a specific transcript, with a custom merge window
+aw-watcher-agent tail-codex --file ~/.codex/sessions/2026/05/29/rollout-...jsonl --pulsetime 5
+```
+
+A cursor per transcript (in the same state directory) records what was already
+emitted, so it is safe to run `tail-codex` repeatedly from a timer or after
+each Codex run.
+
+## Command reference
+
+| Command | Purpose |
+|---------|---------|
+| `ensure-bucket` | Create the session bucket if missing |
+| `emit-start` | Record session start (zero-duration placeholder) |
+| `emit-end` | Replace the placeholder with one event carrying duration + `--outcome` |
+| `emit-activity` | Record one tool-activity heartbeat (`--tool` required) |
+| `tail-codex` | Emit per-tool activity from a Codex rollout transcript |
+| `tail-claude-code` | Emit session working blocks from Claude Code transcripts (no hooks) |
+
+Global flag: `--strict` (exit non-zero on errors). Run
+`aw-watcher-agent <command> --help` for all options.
+
+## Related
+
+- [gptme-sessions](../gptme-sessions/README.md) — session tracking and
+  analytics on the agent side (this watcher puts the same sessions on your
+  ActivityWatch timeline).
+- [gptme-activity-summary](../gptme-activity-summary/README.md) — summarizes
+  agent activity, including ActivityWatch data.

aw_watcher_agent-0.2.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "aw-watcher-agent"
+version = "0.2.0"
+description = "ActivityWatch watcher for AI coding assistants (gptme, Claude Code, Codex)"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["activitywatch", "aw-watcher", "gptme", "ai-agents", "time-tracking"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+# Zero heavy deps by design: vendored stdlib REST client, no aw-client/aw-core.
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+dev = ["pytest>=7.0", "mypy>=1.0.0"]
+
+[project.scripts]
+aw-watcher-agent = "aw_watcher_agent.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aw_watcher_agent"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.mypy]
+check_untyped_defs = true
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true

aw_watcher_agent-0.2.0/src/aw_watcher_agent/__init__.py

@@ -0,0 +1,6 @@
+"""aw-watcher-agent: log AI coding-assistant sessions to a local aw-server."""
+
+from .client import AWClient, AWClientError, Event, DEFAULT_SERVER, utc_now_iso
+
+__all__ = ["AWClient", "AWClientError", "Event", "DEFAULT_SERVER", "utc_now_iso"]
+__version__ = "0.2.0"