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-startposts a zero-duration placeholder;emit-enddeletes it and posts a single event with the full duration plusoutcome. If the session crashes beforeemit-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.
Related
- 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.