ws: Your memory, skills and rules, in any AI

ws turns one policy.toml into each AI tool's own config, answers the tools' hooks, and runs headless jobs that leave one complete record each. Your memory, skills and rules live in plain files that you own, so you can change tool or model without starting again.

ws is a small command-line toolkit. The core is Python 3.11 or newer and the standard library only. It runs on macOS and Linux. On Windows it runs inside WSL2.

Install

Run the installer. It checks the machine, installs the ws command with uv or pipx, and runs a smoke test.

curl -fsSL https://raw.githubusercontent.com/Michael-A-Fry/ws/main/install.sh | bash

Or install the package yourself:

pipx install ws-aitoolkit

For other ways to install, including a pinned version, see Install ws.

First command

ws doctor

ws doctor prints one line per check, each with a stable ID. WS0xx checks cover the machine and WS1xx checks cover the roles you set up (runner, model, budget, secrets, memory, notes, scheduler, notify, backup, usage).

Doctor exits with 1 while anything needs doing, so a new install exits with 1. Run ws init to answer the three setup questions, or ws setup to go step by step. ws doctor --json gives the same report for scripts.

To follow a whole first session, see the first-run tutorial.

Skills

ws install puts six skills in your runner's skills folder: align, checkpoint, taste-gate, dataviz, resume and ship. ws skills lists them per runner. A skill you already have under one of those names stays as it is.

To use ws's version of a name you already have, run ws skills adopt NAME. Yours moves to $WS_HOME/backups/skills/<runner>/ and ws installs its own. ws skills restore NAME takes ws's copy out and moves yours back.

Verify

Check which build you have:

ws version --json

The output has version, git_sha, dirty, build_date, python, install_path and install_source. Each release carries a checksum, a build provenance attestation, a Sigstore bundle and an SBOM. To check them, see Verify a release.

Troubleshooting

For more, see Troubleshoot ws.

Documentation

Start with the documentation map. Pages are grouped as tutorials, how-to guides, explanation and reference (the Diátaxis split).

For contributors: CONTRIBUTING.md, SECURITY.md, SUPPORT.md, CHANGELOG.md and AGENTS.md.

Status

ws is pre-1.0. Commands, JSON output and policy.toml keys can still change between releases, and the CHANGELOG says when they do. Doctor IDs never change meaning once released. Read Known limits before you rely on the wall or the gate.

Licence

ws is Apache-2.0. Contributions need the CLA, signed through a bot on your first pull request.