# stw (Stow) A CLI workspace manager for agents. The agent stows markdown and DuckDB files into a directory it controls; stw keeps the structure navigable and the context cheap to load. The design and the reasoning behind every decision are in [plan.md](plan.md). [CONTRACT.md](CONTRACT.md) is the internal module API. ## Quick start ```sh ./bin/stw init # creates .stw/ and AGENTS.md ./bin/stw new notes/rag.md --about "retrieval strategies" --tags research ./bin/stw write notes/rag.md < draft.md ./bin/stw set notes/rag.md#Chunking/Overlap < para.md # edit ONE section ./bin/stw map # what's here, and why ./bin/stw find "chunk overlap tradeoffs" -k 5 ``` The binary is `stw`, not `stw` — GNUSTW is a symlink farm manager that a lot of machines already have on PATH (plan.md §14). ## Install ```sh curl -fsSL https://raw.githubusercontent.com/gr-ant/stw/main/install.sh | sh ``` Python 3.11+ (for `tomllib`), and nothing else — `stw` is stdlib-only. The installer drops the source tree in `~/.local/share/stw` and a launcher at `~/.local/bin/stw`, pinned to a system interpreter. Re-run it to upgrade; `install.sh --uninstall` removes it and leaves your workspaces alone. The installer also runs `stw init` in the directory you ran it from, so you end up with a working workspace rather than a binary and a homework assignment. It declines to do that in `$HOME` — `curl | sh` is usually run from there, and indexing an entire home directory is not what anyone means by installing a CLI. Point it somewhere explicit with `STW_INIT_DIR`, or skip it with `STW_NO_INIT=1`. An existing workspace is never touched. Knobs: `STW_PREFIX` (default `~/.local`), `STW_REF` (branch/tag/sha), `STW_REPO`, `STW_INIT_DIR`, `STW_NO_INIT`. Set `GITHUB_TOKEN` to install from a private fork. From a checkout instead: ```sh pip install -e . # core pip install -e '.[dev]' # + numpy (vector search), duckdb (artifacts), pytest ``` `numpy` and `duckdb` are optional and lazily imported: `stw read` never pays for either. Without numpy, vector search falls back to pure Python. Without duckdb, everything except `stw db` / `stw sql` works. ## Tests ```sh .venv/bin/python -m pytest tests -q ```