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. CONTRACT.md is the internal module API.
./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 5The binary is stw, not stow — GNU Stow is a symlink farm manager that a lot
of machines already have on PATH (plan.md §14).
curl -fsSL https://raw.githubusercontent.com/gr-ant/stw-cli/main/install.sh | shPython 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:
pip install -e . # core
pip install -e '.[dev]' # + numpy (vector search), duckdb (artifacts), pytestnumpy 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.
.venv/bin/python -m pytest tests -q