Metadata-Version: 2.5
Name: qor-harness
Version: 0.1.0
Summary: Ϙ A TUI-first Python agent harness
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.28
Requires-Dist: textual<9,>=8.0
Description-Content-Type: text/markdown

# Ϙ qor harness

**Strap In!**

Version 0.1.0 · 2026-11-15

qor harness (pronounced “core harness”) is a keyboard-first agent harness for working with
projects from your terminal. It connects to an OpenAI-compatible model endpoint
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.

## Requirements

- Python 3.12 or newer.
- An accessible OpenAI-compatible streaming chat endpoint and a model available
  on that endpoint. qor does not download models or install a model server.
- A terminal for interactive setup and the terminal interface.

## Install

From an unpacked source distribution, use [uv](https://docs.astral.sh/uv/) or
[pipx](https://pipx.pypa.io/):

```sh
uv tool install .
# or: pipx install .
```

You can also install into an active virtual environment with `pip install .`.
The PyPI distribution is not yet published.
To install a built wheel directly, run `pipx install /path/to/qor_harness-0.1.0-py3-none-any.whl`.

## 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 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.

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. 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. |
| `/new` | Start a new session. |
| `/resume` | Continue a saved session for this workspace. |
| `/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.

## License

Apache License 2.0.

Copyright © 2026 Gunnar Leffler.
