workrail 0.3.1

A local-first workstream journal for developers and AI coding agents.

WorkRail

WorkRail is a local-first workstream journal for developers and AI coding agents.

It records the useful trail around meaningful work: what started, what changed, what got blocked, what should happen next, and how the work finished. WorkRail is intentionally smaller than a task board. It stores structured progress events in a local SQLite database, then turns them into reports, JSON state, and a read-only dashboard.

Why WorkRail

• Keep a compact timeline for work that spans more than one command or message.
• Let AI coding agents leave useful progress notes without dumping full transcripts.
• Generate daily and weekly Markdown reports from structured events.
• Inspect the current workstream from scripts with JSON output.
• Keep data local by default, with no service account or hosted backend required.

Install

Install from PyPI:

pip install workrail

If the package has not been published yet, install from a local checkout:

pip install -e .

Or install directly from GitHub:

python -m pip install "git+https://github.com/xu-sheng-dev/workrail.git"

For development:

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

On macOS or Linux:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

WorkRail has no runtime dependencies outside the Python standard library.

Quick Start

workrail start "Fix token expiry handling"
workrail checkpoint "Found a timestamp unit mismatch"
workrail note "Backend returns seconds while frontend expects milliseconds"
workrail next "Verify with local mock data"
workrail done "Fixed the conversion and passed related tests"
workrail report today

WorkRail keeps one current rail. If another rail is already active, start fails by default so you do not accidentally mix two workstreams. Finish it, abandon it, or intentionally replace it:

workrail abandon "No longer current"
workrail start "New task" --force

Use --help to inspect the CLI:

workrail --help
workrail start --help

Agent Usage

WorkRail is designed to be easy for coding agents to use while they work.

workrail current --json
workrail start "Improve test coverage" --source agent --project auto --quiet
workrail checkpoint "Added storage regression tests" --source agent --quiet
workrail done "Implemented tests and verified with pytest" --source agent --quiet

The bundled skill gives agents a small policy for when to log progress, when to record a blocker, and when to stop. Install it into a supported agent skills directory:

workrail install-skill --agent codex     # ~/.agents/skills (shared with OpenCode)
workrail install-skill --agent claude    # ~/.claude/skills
workrail install-skill --agent opencode  # ~/.agents/skills (same as codex)

codex and opencode both resolve to ~/.agents/skills, the common discoverable directory; running both just rewrites the same files. Install for claude separately when you want it visible to Claude Code.

You can also install to a custom directory:

workrail install-skill --target ./installed-skills --force

With --agent auto, WorkRail installs into the only existing supported agent directory. If multiple supported directories exist, specify --agent or --target. When none exist yet, auto falls back to ~/.agents/skills.

Local Dashboard

Start the read-only dashboard:

workrail web

Open:

http://127.0.0.1:18765

The dashboard binds to 127.0.0.1 by default. Binding to another host can expose local work data on your network.

Commands

Command	Purpose
start	Start a new rail.
note or n	Record a note on the current rail.
checkpoint	Record meaningful progress.
block	Mark the current rail as blocked and record why.
next	Record the next step.
done	Complete the current rail.
abandon	Stop tracking the current rail without marking it done.
current	Show the current rail, optionally as JSON.
today	Show today's workstream.
report	Generate a Markdown report for today or week.
web	Start the local dashboard.
install-skill	Install the bundled agent skill.

Data And Privacy

WorkRail stores data in a local SQLite database. Set WORKRAIL_DB to choose the database file:

set WORKRAIL_DB=C:\temp\workrail.db

On macOS or Linux:

export WORKRAIL_DB=/tmp/workrail.db

Without WORKRAIL_DB, WorkRail uses the standard local app data directory:

Platform	Default location
Windows	%LOCALAPPDATA%\WorkRail\workrail.db
macOS	~/Library/Application Support/workrail/workrail.db
Linux	$XDG_DATA_HOME/workrail/workrail.db or ~/.local/share/workrail/workrail.db

WorkRail includes basic safeguards that reject common secret-shaped content such as token assignments, bearer tokens, private keys, and AWS access keys. Treat this as a guardrail, not a substitute for reviewing what you ask humans or agents to record.

Project Status

WorkRail is alpha software. The first release focuses on a small, stable core:

• Local SQLite storage.
• A compact CLI.
• Agent-friendly JSON output.
• Daily and weekly Markdown reports.
• A read-only local dashboard.
• A bundled agent skill and installer command.

Development

pip install -e ".[dev]"
ruff check .
pytest
python -m build

License

WorkRail is released under the MIT License. See LICENSE.