Your shell already has jq for JSON, grep for patterns, curl for
HTTP. qq is the LLM primitive: pipe text in, get text out, exit
0/1 for yes/no. One API call per invocation. No session, no chat
UI, no filesystem access — it can't read your code or run commands,
and doesn't want to.
Works with any OpenAI-compatible provider (OpenAI, xAI, Anthropic, OpenRouter, Groq, DeepSeek, Ollama). Bring your own API key.
$ git diff --staged | qq "one-line commit header"
Fix off-by-one in pagination bounds
$ cat app.log | qq --if "real error?" && page_oncall
$ qq "curl flag for following redirects"
Use -L (or --location); curl doesn't follow redirects by default.
qq treats the model as a text transform with an optional question.
Pipe a diff in, get a commit header. Pipe logs in, ask which test
failed. Pipe anything in, get back a yes/no exit code.
Typing qq "…" to ask a one-off question works too, but the real
job is composing with pipes, redirects, and &&/||.
Claude Code, opencode, aider are the top-level process — you start
one and it runs the show. qq is a tool the shell calls. That's why
it fits inside scripts, pipes, CI, cron jobs, and git hooks, and they
don't.
$ qq explain SIGKILL
SIGKILL is an uncatchable, unignorable Unix signal used to immediately
terminate a process; it can't be handled or cleaned up by the program,
so the OS stops it right away.
plain text, so it flows into whatever comes next:
$ go test ./... 2>&1 | qq "which test is the real failure?"
$ curl -s https://example.com/page | qq "what is this about?"
$ qq "list 5 common HTTP status codes, one per line" | grep 4
404 Not Found
$ qq "a .gitignore for a Python + Node project" > .gitignore
together from man pages. Pipe straight to a shell to run them on the
spot. -i adds a confirmation prompt before passing down:
$ qq -i "ffmpeg to extract a frame every 10s from input.mp4 into frames/" | sh
$ qq -i "find files under . modified in the last 24h larger than 100MB" | sh
$ qq -i "kubectl: stream logs from every pod with label app=api in namespace prod" | sh
so qq wires up with && and || like any other shell tool:
# page only if the model thinks the log is a real error
$ cat app.log | qq --if "is this log showing a real error?" && page_oncall
# commit only if the diff doesn't sneak in a public-API change
$ git diff --staged | qq --unless "does this touch the public API?" && git commit
# in CI: skip heavy tests when the diff is docs-only
$ git diff origin/main | qq --unless "any code changes?" && go test ./...
Exit 0 = yes, 1 = no, 2 = unknown — the prose still prints.
Full contract in docs/decision-mode.md.
See SECURITY.md before piping untrusted input.
This barely scratches the surface. qq plugs into everything you
already do — pipes, &&, loops, git hooks, CI, cron. Go build
something with it. More in Recipes.
$ go install github.com/mscansian/qq/cmd/qq@latest
That puts a qq binary in $(go env GOPATH)/bin. Make sure that's on
your PATH.
Grab a pre-built binary for your platform from the
releases page and drop it
anywhere on your PATH.
$ curl -L https://github.com/mscansian/qq/releases/latest/download/qq-linux-amd64 -o /usr/local/bin/qq
$ chmod +x /usr/local/bin/qq
Available builds: qq-linux-amd64, qq-linux-arm64,
qq-darwin-amd64 (Intel Mac), qq-darwin-arm64 (Apple Silicon).
Before your first question, you'll need a provider API key — see Configure below.
Run the interactive setup once:
$ qq --configure
It asks for a profile name, a provider, an API key, and a default model. Run it again any time to add another profile or update an existing one.
Need a key? OpenAI ·
xAI (API Keys section). For other providers,
see docs/providers.md.
Switch profiles per-invocation, or skip the config file entirely:
$ qq -p grok "..." # use the 'grok' profile
$ QQ_PROFILE=local qq "..." # via env var
$ qq -m gpt-5.4-mini "..." # override just the model
# env-var-only mode, no config file
$ QQ_API_KEY=... QQ_BASE_URL=... QQ_MODEL=... qq "..."
Any OpenAI-compatible endpoint works, including local ones like Ollama or a custom URL.
docs/— howqqbehaves, flags, config, and caveats.SECURITY.md— threat model and what to avoid piping in.CONTRIBUTING.md— build, test, project layout.
Highlights:
- Asking a question — input shapes and quoting.
- Profiles and configuration — precedence, env vars, file layout.
- Decision mode —
--if/--unlessand the yes/no/unknown contract. - History — record shape, rotation, opt-outs.
- Exit codes — full table and script patterns.
- Troubleshooting — common failures.
- Recipes — CI retry, failure summaries, anti-patterns.
See CONTRIBUTING.md for project layout, build
instructions, and where to start if you want to add a feature.