Metadata-Version: 2.4
Name: workrail
Version: 0.3.0
Summary: A local-first workstream journal for developers and AI coding agents.
Author: xusheng
License-Expression: MIT
Project-URL: Homepage, https://github.com/xu-sheng-dev/workrail
Project-URL: Repository, https://github.com/xu-sheng-dev/workrail.git
Project-URL: Issues, https://github.com/xu-sheng-dev/workrail/issues
Keywords: developer-tools,journal,cli,sqlite,agent
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# WorkRail

![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Status](https://img.shields.io/badge/status-alpha-orange)

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:

```bash
pip install workrail
```

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

```bash
pip install -e .
```

Or install directly from GitHub:

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

For development:

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

On macOS or Linux:

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

WorkRail has no runtime dependencies outside the Python standard library.

## Quick Start

```bash
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:

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

Use `--help` to inspect the CLI:

```bash
workrail --help
workrail start --help
```

## Agent Usage

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

```bash
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:

```bash
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:

```bash
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:

```bash
workrail web
```

Open:

```text
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:

```bash
set WORKRAIL_DB=C:\temp\workrail.db
```

On macOS or Linux:

```bash
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

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

## License

WorkRail is released under the MIT License. See `LICENSE`.
