Agent Worklog

English | 繁體中文

Agent Worklog turns coding-agent sessions into weekly reports for managers, saving engineers time.

Architecture

Agent Worklog runs one of three sources per harness, loads only the sessions that overlap the requested period, groups them by repository, redacts and summarizes the evidence, and writes the Markdown report atomically with owner-only permissions.

Capabilities

Agent Worklog supports OpenCode, Claude Code, and Codex. Across supported coding-agent harnesses, it can:

• Find coding-agent sessions across all projects, no matter which folder you are in.
• Select sessions from recent days, a calendar week, or a specific date range.
• Group Git worktrees that belong to the same repository.
• Keep child and subagent sessions linked to the correct repository, or leave them out with --root-only.
• List each repository's session titles and working folders in the report.
• Summarize model and token usage when the selected harness provides it.
• Check session information for common secret patterns before creating a report or invoking the local narrative opencode run.

Requirements

• Python 3.11 or newer.
• Git available as git.
• One coding-agent harness: OpenCode (default), Claude Code, or Codex. OpenCode needs an opencode executable that provides opencode db and opencode export; the default narrative report also uses opencode run, and the usage section uses opencode stats. Claude Code and Codex need no CLI, only a readable transcript store (~/.claude/projects or ~/.codex).

Installation

The recommended way to install the command-line tool is with pipx:

pipx install agent-worklog

You can also install it in a regular Python environment:

pip install agent-worklog

For development:

git clone https://github.com/mike840609/agent-worklog.git
cd agent-worklog
uv sync --locked --extra dev

Getting started

Check that the selected harness and Git are available:

agent-worklog doctor

Preview how Agent Worklog groups repositories for the previous full week:

agent-worklog scan --period last-week

Create the Markdown report; the default runs your local opencode run to write a narrative weekly review:

agent-worklog report --period last-week

Use --no-llm for the deterministic structured report instead:

agent-worklog report --period last-week --no-llm

The default output is written under reports/.

Those three commands default to --harness opencode. For Claude Code or Codex, add --harness claude-code or --harness codex to each. The narrative default behaves the same for every harness: it reads that harness's sessions and still calls your local opencode run to write the review. Add --no-llm when OpenCode is not installed — the deterministic structured report works for every harness without it:

agent-worklog doctor --harness claude-code
agent-worklog report --harness claude-code --period last-week
agent-worklog report --harness claude-code --period last-week --no-llm
agent-worklog doctor --harness codex
agent-worklog report --harness codex --period last-week
agent-worklog report --harness codex --period last-week --no-llm

Prefer a guided walk-through instead of flags? run asks the same questions one at a time — which harness, which period, how much detail — then previews the scan for your approval before writing the report:

agent-worklog run

Pass --dry-run to print the report to the terminal instead of writing a file.

run and config init need an interactive terminal, so they refuse to run when stdin is not a terminal; the scan and report commands cover the non-interactive route.

Interactive menu

Run the command with no arguments to pick what to do from a menu:

$ agent-worklog
What do you want to do?
  1  Generate a report
  2  Scan sessions
  3  Check setup (doctor)
  4  Edit settings
  q  Quit
Choice:

Each entry runs the matching command, asking only the questions that command cannot answer for itself. Scan sessions asks which harness and then scans the last full week; use run, or scan with its own flags, for any other period. Use agent-worklog --help for the command list, and run a subcommand directly in scripts — with no terminal to prompt at, the menu exits with status 3 rather than reading from stdin.

Command reference

| Command | What it does | |---|---|---| | doctor | Checks that the selected harness and git are ready to use. | | scan | Shows which sessions fall in a period and how they group into repositories. | | report | Writes the Markdown report for a period. | | run | Walks you through the wizard: pick a harness and period, preview the scan, then write the report. | | config | Shows and edits the settings file: path, list, init, set, unset. |

scan and report share these options:

While scan and report are working, they show a transient progress status with the current stage. Session and repository stages also show a completed/total count. --quiet hides the progress status. For report --dry-run, progress is written to stderr so stdout contains only Markdown.

report also accepts:

--detail brief produces a short report for a status update: it keeps the header, and for each repository the Repository: remote line, the session counts, and the summary and up to five each of Completed, Problems Resolved, and In Progress. It leaves out Key Files, Directories, Sessions, Branches, and the usage table. Warnings are always kept, at both detail levels, because they report data the tool could not read rather than work you did.

doctor also accepts --harness NAME, --quiet, and --verbose. --quiet hides the list of checks and reports only through the exit code; --verbose does not change what doctor prints. With --harness claude-code, doctor checks that the configured ~/.claude/projects directory exists and is readable, instead of checking for the opencode executable and database. With --harness codex, doctor checks that the configured ~/.codex directory exists and is readable, and reports which discovery path it will take: the state database by name, or directory scan when none is present.

Three rules apply:

• Give exactly one of --days, --period, or --since (scan and report).
• Use --until only together with --since (scan and report).
• Do not use --verbose and --quiet together (all three commands).

Configuration

Agent Worklog reads every setting from an environment variable, and reads a settings file for the ones the environment does not set. For each setting it takes the environment variable, then the settings file, then the default.

To set everything up at once, config init walks through every setting, showing the value in force in brackets. Press Enter to keep it:

$ agent-worklog config init
Press Enter to keep the value in brackets. Every setting is optional.
report.timezone [Asia/Taipei]:
llm.model [gpt-5-mini]: gpt-5
Wrote 1 setting to /home/dev/.config/agent-worklog/config.env

Or set a value once, in the settings file:

agent-worklog config set opencode.cli.model deepseek-r1
agent-worklog config set report.timezone Europe/Berlin
agent-worklog config set llm.model            # leave the value out to be asked for it
agent-worklog config list

config list shows every setting with its current value, whether that value came from the environment, the file, or the default, and what the default is. Every setting is optional: an empty value restores the default, and so does unset.

agent-worklog config set opencode.cli.model ""
agent-worklog config unset report.timezone

agent-worklog config path prints the file location. Set AGENT_WORKLOG_CONFIG_FILE to use a different file.

Variable names start with AGENT_WORKLOG_, with __ between parts of a setting name. An exported variable overrides the file for that shell:

export AGENT_WORKLOG_REPORT__TIMEZONE="Asia/Taipei"
export AGENT_WORKLOG_REPORT__OUTPUT_DIRECTORY="reports"
export AGENT_WORKLOG_HARNESSES__OPENCODE__CLI__EXECUTABLE="opencode"
export AGENT_WORKLOG_HARNESSES__OPENCODE__CLI__SANITIZE="false"
export AGENT_WORKLOG_HARNESSES__OPENCODE__CLI__RUN_TIMEOUT_SECONDS="600.0"
export AGENT_WORKLOG_HARNESSES__OPENCODE__CLI__MODEL=""

See the configuration guide for a complete list of settings.

Privacy

OpenCode exports are raw by default so reports retain useful work details. Agent Worklog redacts common secret patterns locally. The default report hands a grouped, redacted raw transcript to the locally installed opencode run, which writes the narrative; nothing leaves your machine and no API key is needed. Use --no-llm for the deterministic structured report. Use --sanitize for OpenCode's stronger redaction, which intentionally removes most work evidence. Reports may still contain private goals, filenames, commands, and full working paths — always review a report before sharing it.

See Privacy and security for the full details about data safety and current limits.

Exit codes

If one session cannot be read, Agent Worklog skips it and adds a warning to the report. If no sessions can be read, the command stops with an error instead of creating an empty report.

Support and limits

OpenCode, Claude Code, and Codex are the supported tools, selected with --harness. Markdown is the only report format, and Agent Worklog keeps no cache between runs.

• Usage guides — reporting periods, subagents, repository grouping, narrative and structured reports, output handling.
• Usage statistics — how the usage section is built and the window caveat.
• Current support and limits — the full per-harness caveat list.

Development checks

uv sync --locked --extra dev
uv run pytest --cov=agent_worklog --cov-fail-under=80
uv run ruff check .
uv run pyright
uv build

See Releasing Agent Worklog for release instructions.

License

MIT