Skip to main content

aw-watcher-agent

An ActivityWatch 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.

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

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

# 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:

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:

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:

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

  • gptme-sessions — session tracking and analytics on the agent side (this watcher puts the same sessions on your ActivityWatch timeline).
  • gptme-activity-summary — summarizes agent activity, including ActivityWatch data.

Metadata

Release files for aw-watcher-agent 0.2.0

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

Source distribution (sdist)

Source distribution for aw-watcher-agent 0.2.0
File Size Uploaded Provenance Actions
aw_watcher_agent-0.2.0.tar.gz 23.9 kB Without provenance Details for aw_watcher_agent-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aw-watcher-agent 0.2.0
File Interpreter ABI Platform Actions
aw_watcher_agent-0.2.0-py3-none-any.whl Python 3 none any Details for aw_watcher_agent-0.2.0-py3-none-any.whl

Total release size: 43.8 kB

Release files / aw_watcher_agent-0.2.0.tar.gz

Download URL aw_watcher_agent-0.2.0.tar.gz
Size 23.9 kB
Tags Source
SHA-256 checksum
How to use checksums
ee665043ef43b095301842c3e0972fd88635e9701a13aa87cf68df2f831856be
BLAKE2b-256 checksum
How to use checksums
18030a556eb5d75c010e2077e489016bf402d4d777991c01574c71af0fd6dde1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / aw_watcher_agent-0.2.0-py3-none-any.whl

Download URL aw_watcher_agent-0.2.0-py3-none-any.whl
Size 19.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
11e36beb4106e7e231f10ab2e58ff6920f252449ce8dc7fc7372208d2ca485e5
BLAKE2b-256 checksum
How to use checksums
25a219e7ea34e571ed849245eff64f279bc3dddbc6c980b5dba9d536e2309265
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for aw-watcher-agent 0.2.0

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.2.0 This release

2 release files No 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