shoka 0.18.0

shoka (書架, "bookshelf") is a repository workspace manager written in Rust — a modern, jj-aware successor to ghq and rhq. It clones repos into a flat <root>/<host>/<owner>/<name> layout, lets you fuzzy-cd between them, runs commands in parallel across the whole shelf, and surfaces every repo's working state at a glance via a TUI dashboard.

Why another one

ghq and rhq nailed "where do I clone things" — but they're git-only and stop at list / look. shoka picks up from there:

• jj as a first-class VCS alongside git — shoka clone / exec work for both, no ghq-jj shim needed.
• TUI dashboard (Phase 2) for the whole shelf at a glance.
• Profiles to keep work / personal / oss separated.
• Routes for per-org clone destinations + per-route VCS / protocol.
• AGENTS.md aware for AI-heavy workflows (shoka list --has-agents).
• ghq layout compatible — drop-in for existing ~/ghq/... trees via shoka import.
• In-process git via gix — no git subprocess fan-out, so import over a large shelf stays fast even on Windows where CreateProcess dominates the cost.

Install

cargo install shoka

Pre-built binaries for Linux / macOS / Windows are attached to each GitHub release.

Quick start

# 1. (optional) adopt an existing ghq tree
shoka import ~/ghq

# 2. or clone fresh
shoka clone yukimemi/shoka          # → <root>/github.com/yukimemi/shoka

# 3. see what's on the shelf
shoka list

# 4. jump into one (with the shell wrapper installed — see below)
s shoka

# 5. run something across everything (or a tag-filtered subset)
shoka exec --tag rust -- cargo check

Commands

shoka exec is the transparent escape hatch: shoka never interprets the command. shoka exec -- git fetch, shoka exec -- jj git fetch, shoka exec -- cargo check all work the same way. Output from each repo is captured and printed as a banner-headed block when the process exits, so parallel runs don't interleave into nonsense.

Shell integration

A child process can't chdir its parent shell — kernel rule, no escape on any OS shoka cares about. So shoka init-shell emits a shell function that claims the shoka name itself, intercepts the cd and tui subcommands (which need to chdir the parent), and transparently passes every other subcommand through to the binary. The user sees one shoka they can run any subcommand against; the wrapper is invisible until they touch cd or tui.

Behavior of the installed function:

• shoka (no args) — opens the TUI dashboard, Enter selects and cds into the highlighted repo.
• shoka cd [hint] — fuzzy picker (or direct hint), cds on selection. The path travels out-of-band via a SHOKA_CD_OUT sidechannel file so the interactive prompt UI can render normally.
• shoka tui [--tag …] — same as bare shoka, with explicit args.
• shoka <anything-else> — passes through to the binary unchanged (shoka clone <url>, shoka list, shoka exec …, shoka --version, …).

PowerShell

# one-shot (current session):
shoka init-shell powershell | Out-String | Invoke-Expression

# persistent (append to $PROFILE — create it first if missing,
# which it is on a fresh PowerShell install):
if (!(Test-Path $PROFILE)) { New-Item -Type File -Path $PROFILE -Force | Out-Null }
shoka init-shell powershell | Add-Content $PROFILE
. $PROFILE

bash / zsh

# bash — add to ~/.bashrc:
eval "$(shoka init-shell bash)"

# zsh — add to ~/.zshrc:
eval "$(shoka init-shell zsh)"

fish

# ~/.config/fish/config.fish:
shoka init-shell fish | source

Pass --name s (or any other identifier) to install the function under a shorter alias instead of shadowing shoka. The alias behaves the same — s opens the TUI, s cd <hint> picks, s clone <url> passes through.

Configuration

config.toml lives at the OS-standard config dir (Linux $XDG_CONFIG_HOME/shoka/, macOS ~/Library/Application Support/yukimemi.shoka/, Windows %APPDATA%\yukimemi\shoka\config\). A starter is auto-written on first run, so root is the only key you usually need to touch.

Minimal example:

[global]
root = "~/src"

Reference

[global]

[global.ui]

[global.shell]

[global.cache]

[[routes]]

Clone-destination routing, evaluated top-to-bottom at clone time — the first matching route wins. A matched route's set fields override the corresponding [global] values; unset fields fall through.

[profiles.<name>]

Selected via --profile <name> / $SHOKA_PROFILE / global.default_profile. Set fields override [global]; unset fields fall through.

Full example

[global]
root = "~/src"
default_host = "github.com"
default_protocol = "https"
default_vcs = "auto"
exec_concurrency = 8

[global.ui]
own_owners = ["yukimemi"]
cd_page_size = 15

[global.shell]
cd_command_name = "s"

[global.cache]
background_refresh = true
refresh_threshold_secs = 60
parallel_repos = 8

[[routes]]
pattern = "host:github.com/mycompany"
root = "~/src/work"
default_protocol = "ssh"

[profiles.work]
default_host = "github.mycompany.com"

[profiles.work.git_config]
"user.email" = "work@example.com"

Precedence for clone destinations is profile.root (when set) > first matching [[routes]] entry > [global].root.

Layering & templating

Files in the same dir matching config.*.toml are layered on top (alphabetical order; config.local.toml last wins). Point at a specific file with --config PATH or $SHOKA_CONFIG. All values flow through teravars so a [vars] table (with helpers like home() / env(name=...) / is_windows()) self-references and resolves before deserialization.

Roadmap

• Phase 1 — CLI MVP ✅ clone / import / list / cd / exec / prune / cache, shell integration, completion. Done.
• Phase 2 — TUI dashboard ✅ ratatui + crossterm + nucleo fuzzy. Per-repo cached status (branch / ahead-behind / dirty) from gix, open PR count + CI status from octocrab. Done.
• Phase 3 — Polish. OSC 7 cwd hint ✅ (cd / tui announce the picked repo's dir so new tabs/splits inherit it). shoka new scaffolding ✅ (gh repo create + clone + kata init). Contribution-graph column ✅ (per-repo commit-activity sparkline in the TUI). Still open: per-profile route overrides, bulk org-move follow.

Development

cargo make check        # fmt + clippy + locked check + tests
cargo make pre-release  # the whole check suite, exactly as CI runs it

PRs go through Gemini Code Assist + CodeRabbit reviewers on top of standard CI. The yukimemi/* convention is: renri worktrees + kata apply for the shared template, see AGENTS.md for the details.

License

MIT — see LICENSE.