Workline turns AI work traces into reportable, trackable progress. It is built for people who use Codex, Claude Code, and similar coding Agents heavily, and want a low-maintenance way to summarize what actually happened.
Current status: early release. The project focuses on local evidence first; it does not upload your Agent logs.
Workline reads local Codex session facts and Claude Code history facts, then generates Markdown artifacts for weekly reporting.
It is designed to answer:
- What work happened in the selected period
- What appears complete, with evidence
- What is still in progress
- What can be reused in a human-facing progress report
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.
Prerequisite: Node.js >=24.0.0.
Use this path when you want the latest published release:
npm install -g worklineTo upgrade later:
npm install -g workline@latestUse 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 linkIf you already have a local checkout:
npm install
npm linkInstall the Agent-facing Workline skill for Codex and Claude:
workline install-skill --target bothBy default, Workline reads:
- Codex sessions from
$CODEX_HOME/sessionswhenCODEX_HOMEis set, otherwise from your user home.codex/sessionsdirectory - Claude Code history from
$CLAUDE_CONFIG_DIR/projectswhenCLAUDE_CONFIG_DIRis set, otherwise from your user home.claude/projectsdirectory
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 report 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/projectsThe printed path is an intermediate Agent context file. The final user-facing report is written by the Agent to the Final report path declared inside that context.
Use workline --facts only when you explicitly want the internal fact/debug summary.
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 reports may still contain local paths, project names, branch names, command summaries, and inferred work outcomes. Review output before sharing it with others.
- 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 weekly report is written by the current Agent from generated local context, not by a full deterministic renderer.
- Low-confidence follow-up items should be reviewed by a human before becoming tasks.
Workline is open source under the MIT License.
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.
Before installing, verify:
node --version
npm --version
git --versionNode.js must be >=24.0.0. If Node is too old, stop and tell the user to upgrade Node before continuing.
Use:
npm install -g worklineTo upgrade an existing global install, use:
npm install -g workline@latestUse 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 linkIf the repository is already cloned, run only npm install and npm link from the repository root.
Run:
workline --context --print-output-pathExpected result: an Agent context Markdown file path is printed. Treat that path as an intermediate file, not as the final weekly report.
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 Agent-facing skill:
workline install-skill --target bothTargets:
codex: installs to the user-level Codex skills directoryclaude: installs to the user-level Claude skills directoryboth: installs both; this is the default
After installing, verify the printed SKILL.md paths if the user asks whether installation is complete.
For Agent-written final reports, generate context with:
workline --context --print-output-pathTreat stdout as path-only output. Read the generated context file, then write the final report to the Final report path declared in that context.
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>Use workline --facts only for deterministic fact/debug summaries.
Use workline --context for Agent-facing context.
Use $workline, /workline, Workline wording, or a natural-language weekly request for the final human-facing report 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 weekly report.
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.
Do not copy compact internal evidence IDs such as [E1] into the final report. 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.
After the final Markdown report is written successfully, delete the generated agent-context file. If final report writing fails, preserve the context file and tell the user its path so the workflow can be recovered.
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.
Treat Workline as MIT-licensed open source software.