A local tool for one Python folder

Q: When should I use py-harness?

Use it on one Python project: ask a question, write a test, fix a bug, or add a small function. It runs on your machine and only changes files in the folder you name. Daily work is py-harness plus a local 8B model.

Q: Is py-harness everyday-ready?

Not yet. Live Action parse on 29 Aug 2026 was 2 out of 3. Do not call it everyday-ready until eval_everyday.py --live beats an untuned 8B on parse rate and a real fix of at least 1 KB.

Q: What is the public 0.5B model for?

YauhenBichel/python-vibe-0.5b is a style prior. Held-out vibe tasks scored 0 out of 4. It misses Action lines. Do not train more 0.5B weights for agency.

Yauhen Bichel

A local tool for one Python folder

py-harness is a command-line tool. You point it at one Python project. It can answer a question, write a unit test, fix a failing test, or add a small function. It only reads and writes files in that folder.

Install See a demo

Commands

brief

Lists the files in the folder. No model needed.

ask

Answers a question. Does not change files.

run

Changes files, then runs the tests.

Try it

python3 -m venv .venv && source .venv/bin/activate
pip install py-harness-cli

The command is py-harness. The PyPI name is py-harness-cli. Do not pip install py-harness. Activate the virtualenv first (source .venv/bin/activate). If the shell says command not found, the virtualenv is not active.

demo/orders is the sample. pip install does not download it. Clone, then stay in that folder. Do not brief the repository root.

git clone https://github.com/YauhenBichel/py-harness.git
cd py-harness/demo/orders
py-harness brief
py-harness ask  "what does compute_total return?"
py-harness run  "write tests for apply_discount"
py-harness run  "find the NameError and fix it"
py-harness run  "add a function total_lines and a test"

Do not run brief on the py-harness repository root. That scans hundreds of files. Another project:

py-harness ask ~/app "what does add return?".

On a large project add --scope src. Full install steps: Start.

This site

Page	What is on it
Start	Install, then the four commands
Commands	Every flag, the Python API, and the local HTTP server
Live	A recorded session
Demo	Eleven sample tasks and what happened
Folders	What each directory in this repository is
Editors	VS Code and Cursor
Results	Measured scores
References	Papers the design sits on
Architecture	How `src/harness/` is layered

Limits

It does not browse the web or run arbitrary shell commands. run keeps a .bak of each file it edits. The NameError and total_lines samples on demo/orders are built into the tool; they do not call a model.