ws

Try-style workspace switcher & scaffolder written in Go.

ws keeps all of your project directories under a predictable root (default ~/ws), lets you jump between them with a fuzzy-search TUI, and bootstraps new ones using language-specific templates.

Table of Contents

• Installation
  • Quick Install
  • Shell Initialization
  • Completions & Docs
• Getting Started
• CLI Usage
• Templates
• Configuration
• Performance Tuning
• Hooks
• TUI Reference
• Notes
• Troubleshooting

Installation

Quick Install

• Build locally: make build (binary drops at ./bin/ws)
• Install a prebuilt single-file binary: curl -L <your-release-url>/ws-darwin-arm64 -o /usr/local/bin/ws && chmod +x /usr/local/bin/ws

Shell Initialization

• bash/zsh: ./ws init | source /dev/stdin to test; persist it by appending once to your profile, e.g., ./ws init >> ~/.zshrc or ~/.bashrc.
• fish: run ./ws init, then paste the printed Fish snippet into ~/.config/fish/config.fish (append once so future shells have the functions)

Completions & Docs

• Bash: ws completion bash > /etc/bash_completion.d/ws (or another directory sourced by your profile)
• Zsh: ws completion zsh > ${fpath[1]}/_ws (choose any writable directory in $fpath)
• Fish: ws completion fish > ~/.config/fish/completions/ws.fish
• Man pages: ws man ./dist/man && sudo cp dist/man/*.1 /usr/local/share/man/man1 && mandb
• make docs builds ./bin/ws and writes all completions + man pages under dist/

Local build & packaging

make dist       → build binaries for macOS & Linux, produce tarballs + SHA256SUMS.txt
make build      → build current platform only
make docs       → completions + man pages
make clean      → clean artifacts

Getting Started

1. Export WS_PATH=~/ws (or rely on the default).
2. Run ws to open the TUI, search existing workspaces with live filtering, and hit Enter to open one.
3. Create something new with ws new demo --type go or jump straight into ws demo (auto-creates if missing).
4. Optional niceties:
   • Add shell init output to your profile so ws aliases/functions stay current.
   • Install completions + man pages for inline help.

CLI Usage

Core Navigation

• ws — launch the TUI with live search plus a “+ Create” row.
• ws <name> — jump to (or create) a workspace named <name> via the shell helper _rt.
• ws edit <name> — open a workspace with WS_EDITOR/EDITOR.
• ws ls — print Name/LastTouched/OpenCount/Score table.

Creation & Scaffolding

• ws new [name] --type go — scaffold from embedded templates (go, node, ruby, python, php, rust).
• ws clone <url> [name] — clone a Git repo into a dated workspace.
• ws worktree dir [name] — create a Git worktree under WS_PATH.
• ws . [name] — shortcut for ws worktree dir using the current repo.

Maintenance & Diagnostics

• ws rm <name> — delete a workspace (falls back to renaming it to <name>.deleted-<timestamp> if removal fails).
• ws doctor — show environment + config diagnostics.
• ws version / ws --version — print ws <semver> (<commit>).

Templates

Template	Files (copied verbatim)
go	cmd/app/main.go, internal/app/app.go, go.mod, Makefile, .gitignore
node	src/index.ts, package.json, tsconfig.json
ruby	bin/app, lib/app.rb, Gemfile
python	pyproject.toml, src/app/__init__.py, src/app/main.py
php	public/index.php, src/App.php, composer.json
rust	src/main.rs, Cargo.toml

Set WS_TEMPLATES_PATH=/path/to/templates to point at a directory that contains per-language folders (e.g., /path/to/templates/go/...). Files inside override folders are used first; anything missing falls back to the embedded defaults so partial overlays work fine.

Configuration

• WS_PATH — workspace root (default ~/ws)
• WS_DATE_FORMAT — Go time layout used for directory prefixes (default 2006-01-02)
• WS_EDITOR / EDITOR — editor command used by ws edit
• WS_TEMPLATES_PATH — optional path whose <type>/... folders override embedded templates
• WS_DB_PATH — BoltDB path for recency/open-count tracking
• WS_INDEX_CACHE_PATH — JSON cache file for workspace scans (default ~/.cache/ws/index.cache)
• WS_INDEX_CACHE_TTL_MS — cache freshness window in milliseconds (default 3000, clamped 0–600000)
• WS_TUI_DEBOUNCE_MS — debounce window for TUI searches (default 120, clamped 50–1000)
• TOAST_MS — toast lifespan in milliseconds (default 2000, clamped 800–5000)

Performance Tuning

• Workspace scans write to ~/.cache/ws/index.cache (override with WS_INDEX_CACHE_PATH). Entries capture directory names/paths/mtimes and invalidate when WS_PATH changes, the fingerprint drifts, or the TTL elapses.
• WS_INDEX_CACHE_TTL_MS=0 forces live scans every time; raise it (max 600000) to keep large caches warm.
• The TUI throttles Search calls via WS_TUI_DEBOUNCE_MS. Lower values favor responsiveness, higher values reduce filesystem churn.
• All performance knobs are opt-in environment variables; defaults already target fast interactive use.

Hooks

ws can run custom scripts around lifecycle events. Place executables under ~/.config/ws/plugins.d/<event>.d/ (override with WS_PLUGINS_PATH=/path/to/plugins). Scripts inside <event>.d run first, followed by any scoped to <event>.d/<type>/ (e.g., post_create.d/go/). Everything runs sequentially in lexical order with a hard cap of 64 scripts per event.

Supported events:

• pre_create, post_create
• pre_clone, post_clone
• pre_worktree, post_worktree
• pre_open, post_open (fires for the TUI, ws edit, and _rt jumps)

Each hook receives JSON on stdin plus helper environment variables. Example payload:

{
  "event": "post_create",
  "ws_path": "/Users/alice/ws/2025-03-15-demo",
  "ws_name": "demo",
  "type": "go",
  "repo_url": "",
  "branch": "",
  "timestamp": 1710500000,
  "env": {
    "WS_PATH": "/Users/alice/ws",
    "WS_DATE_FORMAT": "2006-01-02",
    "WS_TEMPLATES_PATH": "",
    "WS_DB_PATH": "/Users/alice/.local/share/ws/ws.db"
  }
}

Environment variables exported for each script: WS_EVENT, WS_WORKSPACE_PATH, WS_WORKSPACE_NAME, WS_TYPE, WS_REPO_URL, WS_BRANCH, plus the ambient shell env. A tiny hook might look like:

#!/bin/sh
read payload
printf "%s\n" "$payload" >> "$WS_PATH/hooks.log"

Behavioral notes:

• Default timeout is 3s per script. Override with WS_HOOK_TIMEOUT_MS (clamped 100–60000). Timed-out processes are killed and logged.
• Script stderr is forwarded to the user; stdout is ignored unless you redirect it yourself.
• Non-zero exits and timeouts are warnings by default and do not stop the main command. Set WS_FAIL_ON_HOOK_ERROR=1 to make failures fatal.
• Missing plugin directories are ignored, so you can adopt hooks gradually.

TUI Reference

Keybindings

• Enter — open the highlighted workspace or run “+ Create”
• ↑/↓ or Ctrl-P/N or J/K — move the selection
• e — open the highlighted workspace in WS_EDITOR/EDITOR
• x — start the remove confirmation prompt
• Esc — cancel prompts/help/toasts or exit the app
• ? — toggle the in-app help overlay

Polish & Behavior

• Searches run asynchronously with debounce so fast typing never blocks the UI; a spinner stays visible until the first results land.
• The footer shows the ws version (left), resolved WS_PATH (center), and live result count (right).
• Error/success toasts appear above the footer and auto-dismiss after TOAST_MS, keeping feedback inline.
• Pressing x prompts Remove '<name>'? [y/N]; only y/Y/Enter proceeds, and ws deletes the directory (falling back to a safe rename <name>.deleted-<timestamp> if needed).
• Pressing e launches the workspace via a non-blocking start and still increments recency metadata.
• The help overlay mirrors the keybindings so you do not have to remember them.

Notes

• _rt is an internal helper invoked by the shell function; you normally never call it directly.
• Store/DB errors are logged but non-fatal, so flows continue running (check ws doctor for details).
• Commands like ws foo, ws edit foo, and ws rm foo resolve to the newest DATE-foo workspace; pass literal names (e.g., 2025-11-08-foo) when you need an exact directory.

Troubleshooting

• “git not found” — install Git and re-run ws doctor (git is required for clone/worktree).
• “no editor set (set WS_EDITOR or EDITOR)” — export WS_EDITOR="code -w" (or your preferred command) before running ws edit.