Agent Worklog

English | 繁體中文

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

Architecture

flowchart LR
    subgraph Sources["Session sources"]
        OC["OpenCode<br/>(opencode db + export)"]
        CC["Claude Code<br/>(~/.claude/projects transcripts)"]
        CX["Codex<br/>(~/.codex state DB or rollouts)"]
    end

    subgraph Pipeline["Scan pipeline"]
        SC["ScanService<br/>discover → load → filter"]
        RV["RepositoryResolver<br/>origin → common dir → harness → path"]
    end

    subgraph Report["Report pipeline"]
        EX["Extraction<br/>evidence + 300-char cap"]
        RD["Redaction<br/>secret patterns"]
        SU["Summarizer<br/>rule-based or LLM"]
        US["Usage stats<br/>opencode stats or session tokens"]
        RE["MarkdownRenderer"]
        WR["Atomic write<br/>0600 on POSIX"]
    end

    CLI["doctor / scan / report"] --> OC
    CLI --> CC
    CLI --> CX
    OC --> SC
    CC --> SC
    CX --> SC
    SC --> RV
    RV --> EX
    EX --> RD
    RD --> SU
    US --> RE
    SU --> RE
    RE --> WR

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 sending data to an optional LLM.

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; 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 without using an external LLM:

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 — no OpenCode installation is needed:

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

Command reference

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 uses environment variables for its settings. Variable names start with AGENT_WORKLOG_. Use __ between parts of a setting name. For example:

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_LLM__MODEL="gpt-5-mini"
export AGENT_WORKLOG_LLM__BASE_URL="https://api.openai.com/v1/"
export AGENT_WORKLOG_LLM__ENABLED="false"

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 and uses the rule-based summarizer unless each report invocation explicitly includes --allow-remote-llm. 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, LLM summaries, 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