Ϙ qor harness
Strap In!
Version 0.2.0 · 2026-11-17. Run qor --version to identify your installed build.
qor harness (pronounced “core harness”) is a keyboard-first agent harness for working with projects from your terminal. It connects to an OpenAI-compatible endpoint or your ChatGPT account and gives the model tools to read and edit files and run commands.
Use the interactive terminal interface for a conversation, or run a single prompt from the command line. qor can also work in chat-only mode without workspace tools.
New in 0.2.0
- Deterministic Context Management (DCM), session-wide search, recall and stats.
- ChatGPT-account sign-in and native Ollama/llama.cpp discovery.
- Guided setup, session-only API keys and saved model defaults.
- Bundled-plugin controls, regex file search and a multiline composer with path completion.
Requirements
- Python 3.12 or newer.
- An accessible OpenAI-compatible streaming chat endpoint and model, or a ChatGPT account with access to its agent preview. qor does not download models or install a model server.
- A terminal for interactive setup and the terminal interface.
Install
Install uv with pip (Linux / Bash)
uv can download Python 3.14 and install qor in an
isolated environment. You do not need to replace your system Python, use sudo,
or run an installer script from curl.
Using your existing Python and pip, install uv into your user account:
python3 -m pip install --user uv
export PATH="$HOME/.local/bin:$PATH"
uv --version
Add the export PATH line to ~/.bashrc if that directory is not already on
your PATH. This makes both uv and qor available in new Bash terminals.
If pip reports an externally managed environment, use a user-owned virtual
environment instead. Do not use sudo pip or --break-system-packages:
python3 -m venv "$HOME/.local/share/uv-venv"
"$HOME/.local/share/uv-venv/bin/python" -m pip install uv
export PATH="$HOME/.local/share/uv-venv/bin:$HOME/.local/bin:$PATH"
uv --version
For this alternative, add its export PATH line to ~/.bashrc. If your system
Python lacks pip or venv support, ask your administrator to install those
components through your OS package manager.
Install qor with Python 3.14
First, let uv download Python:
uv python install 3.14
Then choose one installation source.
From PyPI (the latest published release):
uv tool install --python 3.14 qor-harness
From a local wheel (for example, a build someone shared with you):
uv tool install --python 3.14 /path/to/qor_harness-VERSION-py3-none-any.whl
Replace the example path and VERSION with your wheel's actual filename.
Extract the wheel first if it arrived inside a ZIP file. To replace an existing
qor installation with the wheel, add --force to the install command.
A shared development wheel may be newer than the release on PyPI.
Check the installation and start qor:
qor --version
qor
These commands leave your system Python unchanged. Downloads must be allowed by your network policy: uv needs a Python distribution, and even a local-wheel install normally downloads qor's dependencies. A wheel alone is not an offline installation bundle.
Other installation options
From an unpacked source distribution, run uv tool install --python 3.14 ..
If you already have Python 3.12 or newer, you can use
pipx (pipx install qor-harness) or install into an
active virtual environment with pip install qor-harness. The executable is
qor.
Get started
Start in the project directory:
qor
If no model is configured, qor guides you through registering models from an
endpoint and choosing a default. To use your ChatGPT account, run qor login
first; account access and OpenAI Platform API keys have separate billing. See
models and providers.
To use an already installed Ollama model without guided setup, for example:
qor --model gpt-oss:20b
Replace the model name with one available on your server. The default API root
is http://127.0.0.1:11434/v1; use --base-url to choose another endpoint.
Run qor models to list registered models, or qor models add to discover
models from an endpoint. qor does not automatically import another tool's
settings or credentials.
By default, the workspace is the directory where you start qor. Use
--workspace /path/to/project to choose another directory. In coding mode,
qor loads the workspace-root AGENTS.md, if present, as project guidance.
Tools and safety
Trusted mode is the default. The model can read and edit files and run shell commands without routine approval. Commands run with your OS permissions; Bash is not sandboxed. Run qor only with models, endpoints and projects you trust.
- Start with
qor --reviewto review edits and commands before they run in the terminal interface. - Start with
qor --chatfor chat-only mode without workspace tools. - Use
/chatand/codingwhile idle to switch modes without losing the conversation.
The opening titles play the first time each new version runs. Any key skips
them. Run qor --intro to see them again.
Review mode does not approve operations in headless runs: operations that need approval are denied instead.
In the terminal
Type a message and press Enter. Use Alt+Enter or Ctrl+J for a newline. Multiline
drafts grow up to a third of the terminal height, then scroll. Sending returns
the input to one line. Type / to see local commands. A few useful ones:
| Command | Action |
|---|---|
/help |
Show keys and commands. |
/model |
Choose a registered model. |
/providers |
Manage providers and discover models. |
/search WORDS |
Search this session, including saved tool output. |
/recall ID |
Open a saved result. |
/stats |
Show session usage and context-management activity. |
/new |
Start a new session. |
/resume |
Continue a saved session for this workspace, with the model it last used. |
/compact |
Summarise older conversation history. |
/quit |
Exit qor. |
Use Ctrl+C to cancel a run. During a run, you can send another message to steer the next response after the current tool batch.
Run one prompt
Configure a model first using the terminal interface or qor models add. Then:
qor --chat run "Explain this project"
qor --workspace /path/to/project run --jsonl "Inspect the failing test"
Without --jsonl, a headless run prints the final reply. With it, qor streams
runtime events as JSON lines. Put shared options such as --chat, --review
and --workspace before run; put --jsonl after it. Run qor --help and
qor run --help for the available options.
The source distribution also includes model setup and headless guides in release/docs/.
Sessions and context
qor stores settings and model registrations under
${XDG_CONFIG_HOME:-$HOME/.config}/qor/ and session journals under
${XDG_STATE_HOME:-$HOME/.local/state}/qor/sessions/. Original journal entries
remain when older conversation history is compacted. Set an accurate model
context window with /model edit to use automatic compaction effectively.
A resumed session restores completed runs; an interrupted run does not rerun its tools. Chat or coding mode is not saved with a session.
Known limits
- ChatGPT access depends on your account's agent-preview access. It is separate from OpenAI Platform API-key billing.
- When no context limit is known, qor assumes 64K for masking but does not
automatically summarize. Set an accurate limit in
/model editwhen discovery cannot supply one. - The terminal interface is primarily tested on Linux. Clipboard copying has not been verified across terminals.
License
Apache License 2.0.
Copyright © 2026 Gunnar Leffler.
Metadata
Release files for qor-harness 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| qor_harness-0.2.0.tar.gz | 185.5 kB | Without provenance | Details for qor_harness-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| qor_harness-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for qor_harness-0.2.0-py3-none-any.whl |
Total release size: 400.7 kB
Release files / qor_harness-0.2.0.tar.gz
| Download URL | qor_harness-0.2.0.tar.gz |
|---|---|
| Size | 185.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a9c743d658089b05ad8f378c654e25a51c03b16201ccd95487f2075c938d5f2a
|
|
BLAKE2b-256 checksum How to use checksums |
55e2ffa7bb19edfc793c3b8c92e0c276eb8c968e49590bed8f123813bc9f5c44
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.10
|
Release files / qor_harness-0.2.0-py3-none-any.whl
| Download URL | qor_harness-0.2.0-py3-none-any.whl |
|---|---|
| Size | 215.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
986b5c63df5ad1d21864170fcd626d92a61ff2f83aef76e1e93a9eea880d055f
|
|
BLAKE2b-256 checksum How to use checksums |
202072b27cccd7be841b837a7941229d758bbff2c9f33e538fd5b836718e9404
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.10
|
Security for qor-harness 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.