qqqa: A Stateless Two-Binary LLM Wrapper for the Shell

The gap qqqa fills between a chat window and a shell prompt

Copying a question into a browser, reading an answer, and pasting a command back into the terminal is a context switch that costs more than the question is worth. qqqa targets exactly that friction. The README frames the project as a two-in-one, stateless CLI tool that brings LLM assistance to the command line without ceremony, and the naming rationale is explicit: qq means quick question, qa means quick agent, and both are short strings that are easy to type rapidly on QWERTY keyboards with minimal finger movement.

The intended user is someone already working in a terminal who wants a one-shot answer or a single confirmed action, not a conversation. That shows up in the design constraints rather than in marketing language. qq is read-only and has access to no tools. qa can read a file, write a file, or execute a command, but the README states it requires confirmation before running tools. If you want an assistant that remembers what you asked ten minutes ago, this is the wrong shape of tool, and the project says so itself.

Statelessness as the actual architecture, not a slogan

There is no long-running session and no hidden conversation memory stored by the tool. Each invocation is mostly independent and reproducible. That single decision cascades into everything else: the binaries can be piped, scripted, and called from other programs without worrying about a daemon holding state, and there is no server process to keep alive.

The project does allow a narrow exception. Setting "include_history": true in config.json, or choosing history during the qq --init flow, gives what the README calls lowkey continuity. That is the only continuity mechanism described, and it is opt-in.

Context flows in two directions. qq can include the last few terminal commands as hints and will pick up piped stdin if present. qa can read files or run a specific command, but only once per invocation and with safety checks. The once-per-invocation limit is the part that matters most: it caps the blast radius of a bad model response at a single action, and it also means qa cannot chain a read into a write into an execute within one run. If your task needs that chain, you are outside the design.

Profiles and the bring-your-own-subscription path

qqqa ships profiles for OpenRouter (the default), OpenAI, Groq, Gemini (API and CLI), a local Ollama runtime, the Codex CLI, and the Claude Code CLI. An Anthropic profile stub exists in the config but the README states it is not wired up yet, so the Anthropic entry in the init menu is a placeholder until the Messages API work is finished.

The two CLI profiles are the interesting ones because they avoid per-token billing. The codex profile shells out to the Codex CLI instead of hitting an HTTP endpoint, letting you reuse an existing ChatGPT subscription. The README is direct about the cost of that choice: streaming is unavailable, and even without --no-stream, qqqa buffers the Codex response and prints it once. That is a real regression in perceived latency for long answers, and it is not something a flag can fix.

The claude_cli profile uses the claude binary and streams responses the same way API-based LLMs do, so it does not share that limitation. It does require running claude login once. Model pinning differs between the two: Claude takes a "model_override" under model_providers.claude_cli.cli, and the README notes that override applies only to the CLI while qq -m/--model still takes precedence per run.

Getting it installed and configured

Homebrew is the shortest path on macOS and Linux: brew install qqqa. On Linux without Homebrew, download a prebuilt archive from the releases page and place qq and qa on your PATH. The README flags one distribution hazard worth knowing before you start: on Arch Linux, /usr/bin/qq may already belong to another package, so the guidance is to install to a custom directory such as ~/bin and rename if needed, or use cargo install from the repo. Windows users download the archive matching their architecture and add qq.exe and qa.exe to %PATH%.

Configuration is created on first run with safe permissions. The default path is ~/.qq/config.json. If XDG_CONFIG_HOME is set and no legacy ~/.qq/config.json exists, the file goes to $XDG_CONFIG_HOME/qq/config.json instead. That fallback rule is worth reading twice, because it means the location depends on whether a legacy file is present. The init flow is qq --init or qa --init, and it lets you pick the default provider from the list above. If ~/.qq/config.json already exists, init keeps it untouched and explains how to rerun after moving or deleting the file.

Provider keys come from the environment. OpenRouter reads OPENROUTER_API_KEY, and the README notes that first run works as soon as you drop in a key. Pinning a different default is a config edit, for example setting "default_profile": "codex" alongside a profiles block containing "model_provider", "model", and "reasoning_effort".

Where the design gets in your way

The stateless model is a constraint, not just a philosophy. Because qa performs one tool action per invocation, any task that requires inspecting a file before deciding what to write becomes two or more confirmed steps with you in the middle. That is deliberate, and the confirmation requirement is the reason, but it means qa is a single-step agent and should be evaluated as one.

The Codex profile's buffering is the second sharp edge. On a slow model with a long answer, you get no output until the whole response is ready. The README attributes this to the CLI rather than to qqqa, and surfaces stderr and stdout when the binary is missing or exits with an error, which helps with diagnosis but does not change the experience.

There is also a dependency surface that the HTTP profiles do not have. Both CLI profiles require an external binary on PATH and, for Claude, a prior login. If codex or claude is absent, qqqa fails at runtime rather than degrading to an API provider, so the failure mode is a broken invocation rather than a fallback. Finally, the Anthropic API profile is a stub. If Anthropic is your provider of choice and you do not have a Claude subscription to drive claude_cli, the init menu offers you an option that the README says is not wired up yet.

How it compares to an interactive agent CLI

The closest comparison is an interactive terminal agent that keeps a session, accumulates context across turns, and plans multi-step tool use. That category solves a different problem: long tasks where the value comes from the model holding state and chaining actions. qqqa deliberately refuses both. No session, one tool action per run, confirmation before anything executes.

The trade is legibility for capability. With an interactive agent you get fewer round trips and more autonomy, at the cost of a process that accumulates state you cannot fully see. With qqqa you get a command whose behaviour you can predict from its arguments, which is why the README leans on the Unix philosophy framing and pipe composition. If your work is a stream of small questions and single confirmed actions, the stateless version is the better fit. If your work is a long migration script that needs the model to read, decide, and write repeatedly, qqqa will make you the loop, and you will feel it.

Licence, maintenance and what to check first

qqqa is MIT licensed. That is permissive and places few obligations on how you use or redistribute the binaries, though as always the actual terms are in the LICENSE file and this is not legal advice. The practical implication for a tool that shells out to codex or claude is that the MIT grant covers qqqa, not the external CLIs, which carry their own terms tied to your subscription.

Maintenance signals in the supplied material: the repository is not archived, the last push is dated 2026-06-25, and v1.0.0 shipped 2025-11-25. The release cadence before that was quick, with v0.9.2 and v0.10.0 landing within days of each other in November 2025. v0.10.0 added Windows support, streaming by default, and the codex and claude_cli providers, which means the CLI provider path is the newest and least settled part of the tool. v0.9.2 brought clipboard copy, timeouts, and self-signed certificate handling.

Upgrade cost looks low for the HTTP profiles, since configuration is a single JSON file and the binaries are self-contained. The thing to verify before depending on it is the config path resolution on your machine, because the XDG fallback only applies when no legacy ~/.qq/config.json exists. Check that first, then confirm which profile is actually default with a single qq invocation, and test one qa file read to see the confirmation prompt.

Editorial conclusion

Adopt qqqa if you want a pipe-friendly, read-only-by-default LLM command and you are comfortable editing ~/.qq/config.json to pin a provider. Skip it if you need multi-step agent loops or streaming through a subscription CLI profile, since the README states Codex buffers its whole response. Before relying on it, run qq --init, confirm where the config landed (~/.qq/config.json or $XDG_CONFIG_HOME/qq/config.json), and test one qa command with a file read to see the confirmation prompt in your own terminal.

Official sources

1. iagooar/qqqa on GitHub
2. Issues
3. License: MIT
4. README
5. Releases