Metadata-Version: 2.5
Name: qor-harness
Version: 0.2.0
Summary: Ϙ A TUI-first Python agent harness
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: google-re2<2,>=1.1
Requires-Dist: httpx<1,>=0.28
Requires-Dist: pyjwt[crypto]<3,>=2.10
Requires-Dist: textual<9,>=8.0
Description-Content-Type: text/markdown

# Ϙ 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](https://docs.astral.sh/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:

```bash
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`:

```bash
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:

```bash
uv python install 3.14
```

Then choose **one** installation source.

**From PyPI** (the latest published release):

```bash
uv tool install --python 3.14 qor-harness
```

**From a local wheel** (for example, a build someone shared with you):

```bash
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:

```bash
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](https://pipx.pypa.io/) (`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:

```sh
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](docs/models.md).

To use an already installed Ollama model without guided setup, for example:

```sh
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:

```sh
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.
