Skip to main content

Ϙ 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 --review to review edits and commands before they run in the terminal interface.
  • Start with qor --chat for chat-only mode without workspace tools.
  • Use /chat and /coding while 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 edit when 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)

Source distribution for qor-harness 0.2.0
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)

Table of built distributions (wheels) for qor-harness 0.2.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page