Workline

Workline turns AI work traces into a verifiable progress brief. It is built for people who use Codex, Claude Code, and similar coding Agents heavily, and want a low-maintenance way to reconstruct what actually happened before writing accountable progress updates.

Current status: early release. The project focuses on local evidence first; it does not upload your Agent logs.

For Humans

What it does

Workline reads local Codex session facts and Claude Code history facts, then generates a readable progress brief with a supporting ProgressCandidatePacket and evidence references.

It is designed to answer:

• What work happened in the selected period
• What appears complete, with evidence
• What still needs confirmation
• What can become a human-facing progress statement after Agent/user review

Who it is for

This early release is for developers, product builders, and technical leads who use Agent-assisted workflows often enough that their real progress is scattered across local sessions, commands, branches, diffs, and notes.

It is not a team task manager, project management system, or personal desktop assistant.

Install From npm

Prerequisite: Node.js >=24.0.0.

Use this path when you want the latest published release:

npm install -g workline

To upgrade later:

npm install -g workline@latest

Install From GitHub Source

Use this path when you want to test the current source from GitHub before or instead of an npm release:

git clone https://github.com/Ryan-Chiang/workline.git
cd workline
npm install
npm link

If you already have a local checkout:

npm install
npm link

Quick Start

Install the Agent-facing Workline skill for Codex and Claude:

workline install-skill --target both

By default, Workline reads:

• Codex sessions from $CODEX_HOME/sessions when CODEX_HOME is set, otherwise from your user home .codex/sessions directory
• Claude Code history from $CLAUDE_CONFIG_DIR/projects when CLAUDE_CONFIG_DIR is set, otherwise from your user home .claude/projects directory

On macOS and Linux these are typically ~/.codex/sessions and ~/.claude/projects. On Windows they resolve under %USERPROFILE%.

After installation, ask the Agent for a Workline progress summary with $workline, /workline, or a natural-language request such as 生成本周周报.

You can pass source paths explicitly:

workline --context --print-output-path --codex-root ~/.codex/sessions --claude-root ~/.claude/projects

The printed path is an intermediate Agent context file. The context starts with a readable progress brief, then includes a ProgressCandidatePacket and a Statement output path; the Agent audits and confirms the brief before writing any user-facing progress statement.

Use workline --facts only when you explicitly want the internal fact/debug summary.

Privacy

Workline reads local files from your machine and writes Markdown output locally. The CLI does not upload raw Codex sessions, Claude Code transcripts, or generated reports.

Generated context and progress statements may still contain local paths, project names, branch names, command summaries, and inferred work outcomes. Review output before sharing it with others.

Known Limits

• Codex and Claude Code local history extraction are the current first-class Agent sources.
• Git, Slack, email, PR metadata, and other sources are future expansion areas unless already present in local Agent context.
• The final human-facing progress statement is written by the current Agent from generated local context after candidate confirmation, not by a full deterministic renderer.
• Low-confidence follow-up items should be reviewed by a human before becoming tasks.

License

Workline is open source under the MIT License.

For Agents

When To Use

Use workline when the user asks for Workline, $workline, /workline, weekly progress, work summaries, Agent-assisted work recap, 本周周报, 周报, or related reporting material based on local work traces.

Do not treat chat messages, draft notes, or exploratory commands as completed outcomes unless the local facts support that conclusion.

Install Prerequisites

Before installing, verify:

node --version
npm --version
git --version

Node.js must be >=24.0.0. If Node is too old, stop and tell the user to upgrade Node before continuing.

Install From npm

Use:

npm install -g workline

To upgrade an existing global install, use:

npm install -g workline@latest

Install From GitHub Source

Use this path when the user explicitly wants the current GitHub source instead of the published npm package:

git clone https://github.com/Ryan-Chiang/workline.git
cd workline
npm install
npm link

If the repository is already cloned, run only npm install and npm link from the repository root.

Verify Installation

Run:

workline --context --print-output-path

Expected result: an Agent context Markdown file path is printed. Treat that path as an intermediate file, not as the final progress statement.

If the command fails because local Codex sessions and Claude Code history are missing, inaccessible, or empty for the selected period, report that fact directly instead of inventing progress.

Install The Workline Skill

Install the Agent-facing skill:

workline install-skill --target both

Targets:

• codex: installs to the user-level Codex skills directory
• claude: installs to the user-level Claude skills directory
• both: installs both; this is the default

After installing, verify the printed SKILL.md paths if the user asks whether installation is complete.

Generate Workline Context

For Agent-confirmed progress statements, generate context with:

workline --context --print-output-path

Treat stdout as path-only output. Read the generated context file, start from the progress brief, use the ProgressCandidatePacket to audit or repair it, then write the final progress statement to the Statement output path declared in that context when the user wants a written deliverable.

Pass through user-provided time bounds or source paths when relevant:

workline --context --print-output-path --since <instant> --until <instant> --timezone <iana> --codex-root <path> --claude-root <path> --scope <boundary>

Use --scope when the progress statement should stay inside an explicit boundary, such as one client, one product, one launch, or one workstream. Scope is a statement boundary signal for the Agent; it does not create a new task system.

Workline also includes local Git repository evidence from the current workspace, such as branch, HEAD, remote, and dirty status. This is context evidence, not a work item. It is not full GitHub/GitLab PR, issue, or release ingestion.

Command Boundaries

Use workline --facts only for deterministic fact/debug summaries.

Use workline --context for Agent-facing context.

Use workline --help to print CLI usage without generating output.

Use $workline, /workline, Workline wording, or a natural-language weekly request for the Agent-confirmed human-facing progress statement after the skill is installed.

Do not call bare workline; the terminal CLI requires --context, --facts, or an explicit compatible --format output layer.

Do not present workline-facts-*.md as the final progress statement.

Progress Statement Rules

Write outcome-first. Prefer actual state changes and reusable results over implementation steps.

Keep process evidence as support, not as the headline. File edits, commands, config changes, draft docs, and validation runs are evidence unless they clearly represent the user's desired outcome.

Start from the progress brief. Use the ProgressCandidatePacket to confirm, reject, merge, split, or reword its claims before using them.

Do not copy compact internal evidence IDs such as [E1] into the final progress statement. Convert evidence into human-readable descriptions, paths, links, commands, commits, or session references.

Mark low-confidence follow-ups explicitly and leave them for human confirmation.

Keep the default visible surface scan-first and progress-centered. Do not create standalone risk, blocker, next-step, evidence, review, or tradeoff sections unless the user explicitly asks for that mode; fold those signals into the relevant progress item as state, caveat, or confirmation note.

After the final Markdown progress statement is written successfully, delete the generated context file. If statement writing fails, preserve the context file and tell the user its path so the workflow can be recovered.

Troubleshooting

If installation fails, check Node version, npm registry access, npm permissions, and whether the package has been published.

If no facts are found, check the date range, timezone, Codex sessions path, and Claude Code projects path.

If generated context is long, summarize conservatively from the bounded context instead of asking the user to paste raw logs.

If output contains sensitive local paths or private project names, tell the user to review before sharing.

License Handling

Treat Workline as MIT-licensed open source software.