An open-source agent toolkit
Your agents.
Your workspace.
Run QQ in your repository. Connect your existing Codex subscription, give Astra a task, and keep tools and approvals under your control.
01 / Work
Start with your code.
Explore a repository, investigate a failure, or propose a change. Inspect tool actions and results in the terminal.
02 / Connect
Bring your model.
Use the Codex login route for Astra, or configure a supported provider. Your provider’s access rules and usage limits still apply.
03 / Verify
Check the work.
Our JEV integration is being built to review every tool result and completed task. The current QQ release does not yet enforce those reviews.
Download → connect → run
Let’s get you running.
No account on this website. No repository upload here. Start in a checkout you own and understand.
Official QQ v0.1.0. This is the base agent, not the unreleased mandatory-JEV integration.
Extract the archive and put qq on your PATH. Do not
install the unrelated qq package from npm.
Archive layout:
qq-v0.1.0-aarch64-apple-darwin/qq.
Show extraction command
Run from the download folder. This creates the versioned folder shown above.
tar -xzf qq-v0.1.0-aarch64-apple-darwin.tar.gz
Verify the archive checksum
Compare the command result with the release’s SHA-256SUMS file before extracting or installing.
Install for this user only
This creates ~/.local/bin, refuses to overwrite an
existing qq, and updates PATH only for the current
terminal session. It never uses sudo or edits a shell profile.
qq --version
Sign in through the browser QQ opens. Review the requested access. Do not paste a password or token into this website.
qq auth login openai-codex
Check that your account can use Astra:
qq ask --model openai-codex/gpt-6-astra "Reply with pong"
Open a terminal in a repository you own. Begin with this bounded, read-only task. Read-only mode does not allow shell commands, edits, or MCP calls.
qq run --model openai-codex/gpt-6-astra --approval read-only --max-turns 8 --timeout-seconds 120 "Read the README and package manifest. Explain how this project is structured and which test commands it documents. Do not change files or claim to have run tests."
For the interactive interface, run qq in the same
repository. It uses a local background server.
Read about tools and approvals ↗
Troubleshooting and version compatibility
Model error: check the selected provider,
account access, and qq config check.
Store invariant after a downgrade: do not delete the session database. The September 14 release uses schema 28; the September 17 source build uses schema 30. Use a compatible newer binary to keep your history.
macOS paths: use qq config paths.
XDG variables do not isolate QQ’s data on macOS. Check
compatibility before switching binaries against the same store.
JEV integration
Not just
“the agent said so.”
QQ does the work. Tests exercise the result. JEV reviews the evidence.
Review belongs in the runtime.
The required flow is a JEV check after every tool result and every task completion—including child tasks. Missing or failed review must not silently advance the work or mark it verified.
Today’s MCP companion proves that QQ can call JEV with your TypeSafe API key. An agent-requested MCP call does not yet enforce that complete flow. We are not presenting it as the finished integration.
Read the integration guide →Your key belongs in your local secret environment, never this website. JEV receives selected claims and evidence. Review packets for sensitive data; a JEV label does not replace tests or guarantee correctness.
Keep going
Documentation, not guesswork.
What has actually been tested
The macOS Apple silicon v0.1.0 download matches its published checksum and completed an Astra request through an approved Codex login. Source build c404ae53 completed a bounded run and an actual JEV MCP call. This does not establish mandatory checkpoint enforcement or cross-platform reliability.
The JEV companion’s independent synthetic set matched 9 of 12 expected labels. Three disagreed. These results are not an accuracy guarantee.