qsoku

README

qsoku

日本語 | English

One set of shortcuts, shared by the whole team.

Features · Demo · Example · Install · Learn more

qsoku writes a repository's own command shortcuts into a qsokufile, so anyone (or anything) in that repository can run qsoku <name> from anywhere inside it.

Features

• 🔗 Shortcuts that live in the repository — unlike a shell alias, a qsokufile is committed with the repository, so the whole team gets the same shortcuts, and they never leak into your other projects.
• 🧭 The same name from anywhere — qsoku walks up from the current directory to find the one qsokufile in use, the same way git finds .git/.
• 🐚 Always runs with sh — a qsokufile command means the same thing no matter which shell you typed qsoku from, and cds inside it bring your working directory back automatically.
• 🧩 Only three rules of its own — how qsoku finds the qsokufile, what // means, and how it brings the working directory back. Everything else is ordinary sh.
• 🤖 Works for AI agents too — the qsokufile is the repository's own list of commands, so a human and an AI agent can run the same shortcut by the same name.

Demo

Recorded against this very repository: qsoku test is (cd //; go test ./...), run from internal/cli/ — // always finds its way back to the root, no matter where you call it from.

Example

$ qsoku build
building the project
$ qsoku test
testing from /home/you/project

# qsokufile
build: echo "building the project"
test: (cd //; echo "testing from $QSOKU_ROOT")

test uses // to reach the repository root, so it behaves the same whether you run it from the root or three directories down.

Install

go install github.com/amisonnet8/qsoku/cmd/qsoku@latest

Or download a prebuilt binary from Releases (Linux, macOS, Windows).

Then add one line to your shell's startup file (see cli.md for bash/zsh/fish/pwsh specifics):

eval "$(qsoku .shell bash)"

This also wires up shell completion for the names in your qsokufile.

On Windows, qsokufile commands still run under sh — put Git for Windows' sh.exe on PATH. From PowerShell 7+, add Invoke-Expression (& qsoku .shell pwsh | Out-String) to $PROFILE instead; Git Bash works too, the same way as on Linux/macOS.

Adding a shortcut, start to finish (click to expand)

$ qsoku .init
Created /home/you/project/qsokufile
$ qsoku .add build 'echo "building the project"'
$ qsoku .add hello 'echo "hello, $1"'
$ qsoku .list
build: echo "building the project"
hello: echo "hello, $1"

See docs/tour/ for a longer, hands-on walk-through.

Learn more

• Interactive guide — ask questions about qsoku and explore it conversationally (built with Gemini Notebook)
• docs/tour/ — a hands-on walk through qsoku, from an empty qsokufile to shell integration and completion
• docs/reference/ — the formal specification of the qsokufile format and the qsoku command line
• docs/examples/ — qsokufiles you can copy into your own repository

License

MIT (see LICENSE).

---

docs/tour/ · docs/reference/ · docs/examples/ · LICENSE