GitHub - anishalle/wo: wo(rkspace management) [proxy]

wo

wo is a fast workspace jumper for repo-style directories.

It indexes workspaces once, resolves names quickly, and (with shell integration) changes directory and runs trusted hooks.

What `wo` Does

Jump to a workspace by name: wo harp
Browse indexed workspaces in an interactive picker: wo
Resolve ambiguous names with picker/confirmation
Discover workspaces from .git/ or .wo
Run startup hooks and named hook profiles
Support workspace-local and global hook profiles
Provide shell completion for workspace names and hook profile names

Install

make install
# or
./scripts/install.sh

Uninstall

make uninstall
# or
./scripts/uninstall.sh

uninstall removes:

installed wo binary
installed wo man page
runtime SQLite index/trust state (wo.db*)

uninstall keeps:

workspace .wo files
config files

Shell Integration (Required For `cd`)

wo only changes your current shell directory when shell integration is loaded. Without integration, wo prints the resolved path.

# zsh
source <(wo init zsh)

# bash
source <(wo init bash)

# fish
wo init fish | source

After loading shell integration:

wo <TAB> completes workspace names for arg 1
wo <workspace> <TAB> completes hook profiles for arg 2

Quick Start

# index default roots (~/workspaces if present)
wo scan --depth 1

# scan custom roots
wo scan --root ~/workspaces --root ~/src --depth 2

# jump to workspace
wo harp

# jump and run named profile hook
wo harp code

# force global profile
wo harp code --global

# skip all hooks for this invocation
wo harp --clean

# always force picker
wo harp --pick

Workspace Detection

A directory is indexed if it has either:

.git/
.wo

Workspace `.wo` File (TOML)

Place a .wo file at workspace root.

name = "harp" # optional name and owner
owner = "hackutd"

[enter]   # commands that run on enter ( wo harp )
commands = ["echo startup", "nvim ."]
shell = "inherit"

[code]
command = "code ."
chdir = false

[nvim]
comand = "nvim ."
chdir = true   #implicitly true

[test]
commands = ["go test ./...", "make lint"]
chdir = false

Schema notes:

[enter] is startup hooks.
Top-level tables other than name, owner, and enter are hook profiles.
Profiles support command (single), commands (list), and chdir (bool, default true).
chdir = false means: run hooks in workspace, then return to your original directory.
If both startup and profile hooks exist, wo runs startup first, then profile.
Hook failures are printed to stderr; wo continues running remaining hooks.

Global Config

Main app config (`config.toml`)

Location:

os.UserConfigDir()/wo/config.toml
Example by OS:
- macOS: ~/Library/Application Support/wo/config.toml
- Linux: ~/.config/wo/config.toml

Default values:

roots = ["~/workspaces"]

[scan]
depth_default = 1
follow_symlink = false

[search]
backend = "auto" # auto|internal|fzf

[ui]
theme = "gh"

[hooks]
enabled = true

[correction]
enabled = true
min_score = 0.72
min_gap = 0.10

Global hook profiles (`config.wo`)

Location:

$XDG_CONFIG_HOME/wo/config.wo if XDG_CONFIG_HOME is set
else ~/.config/wo/config.wo

Example:

[cursor]
command = "cursor ."
chdir = true

[code]
command = "code ."
chdir = false

Rules:

Global profile names are available to all workspaces.
wo <workspace> <profile> checks workspace profile first, then global.
wo <workspace> <profile> --global forces global profile lookup.
If profile exists in both places, workspace definition overrides global.
[enter] in global config.wo is disallowed; wo warns and ignores it.
Missing requested profile returns an error.

Hook Completion Behavior

For wo <workspace> <TAB>:

workspace profiles are listed first
global profiles are listed after workspace profiles
names are prefix-filtered as you type
duplicate names are deduped with workspace definition winning
[enter] is never shown in profile completion

Command Reference

Top-level usage:

wo [workspace] [profile] [--clean] [--pick] [--global]
wo

Commands:

wo
Opens interactive browse picker.
wo <workspace>
Resolves workspace, changes directory, runs startup hooks.
wo <workspace> <profile>
Resolves workspace, runs startup + selected profile hooks.
wo scan [--root <path> ...] [--depth <n>] [--follow-symlinks] [--prune]
Index filesystem roots.
wo list [--owner <owner>] [--json]
List indexed workspaces.
wo doctor
Run config/db/fzf/root checks.
wo trust list|allow|deny|reset
Manage workspace hook trust decisions.
wo init <zsh|bash|fish>
Print shell integration script.
wo completion <bash|zsh|fish>
Print shell completion script.

Root flags:

--clean skip all hooks for this invocation
--pick force interactive picker even if one exact match
--global use global profile source (requires profile argument)

Trust Model

Workspace hook execution is trust-gated:

first run prompts for trust decision
decision is stored with workspace fingerprint
if .wo changes, trust is re-evaluated

Manage trust:

wo trust list
wo trust allow <workspace>
wo trust deny <workspace>
wo trust reset <workspace>
wo trust reset --all

Global config.wo profiles are considered user-managed and are not trust-prompted.

Troubleshooting

hook profile "<name>" not found:
- Workspace file must be named .wo (not config.wo) inside the repo.
- Global profiles must be in ~/.config/wo/config.wo (or $XDG_CONFIG_HOME/wo/config.wo).
wo prints a path but does not change directory:
- Load shell integration (wo init zsh|bash|fish).
Completion not reflecting latest behavior:
- Reload shell integration in your current shell session.

Notes

fzf is optional. If installed and search.backend=auto|fzf, wo can use it for interactive picking.
WO_DEBUG=1 enables debug logs.

GitHub - anishalle/wo: wo(rkspace management)

wo

What wo Does