tinyharness-lm 0.1.0

tinyharness is the loop that turns an LLM into an agent: it reads, searches and edits your code, runs commands in a sandbox, asks before it changes things, and keeps long sessions inside the context window. It works as a coding agent in your terminal and as a Python SDK for building your own. The agent core is about 9k lines of code with no framework underneath, so you can read the whole thing in an afternoon.

Why tinyharness

• Readable. About 9k lines of code for the agent core (12k with the terminal UI), commented for people learning how agents work. Start with agent/loop.py.
• Any model, even yours. Anthropic, OpenAI, Gemini, xAI, OpenRouter, DeepSeek, Mistral and Groq, each through its own current API, plus any OpenAI-compatible server: vLLM, Ollama, llama.cpp, SGLang.
• Robust with small models. Cut-off replies, empty replies, tool calls written as text, malformed arguments and repeated failures are handled by the harness, so mid-size open models get work done too. How.
• Safe without the friction. Commands run with filesystem and network isolation; routine contained work doesn't ask, while a newly required exact host can be approved without dropping containment. Downloading new executable code asks once; cached tools then run normally, and bare Python installs use a project .venv. API keys never reach the model. Once outside content is in the conversation, anything that could send data out asks a person first.
• Small and fast. Seven core tools and a short prompt (about 3k tokens before your instructions) that stays the same from call to call, so the provider's cache hits.
• Extensible. One Python file with setup(th) adds tools, prompt sections, commands and hooks. Web search, PDFs, subagents and parallel teams are built-in extensions you turn on.

Quickstart

Requires Python 3.11+. Install the command with uv (or pipx):

uv tool install tinyharness-lm     # or: pipx install tinyharness-lm
cd your-project && tinyharness

The first run asks which provider to use and for its API key; one key for any supported provider is enough. uv tool upgrade tinyharness-lm updates it.

In the session, type / to autocomplete commands. The ones you'll use most:

Useful flags: -c (continue the latest conversation), -r (pick one), -p "prompt" (run one prompt and exit), --model provider:model, --mode ask, --cwd <dir>.

Use it from Python

uv add tinyharness-lm              # or: pip install tinyharness-lm

import asyncio
from tinyharness import AssistantText, Session, SessionOptions, ToolUse


async def main():
    async with Session(SessionOptions()) as session:
        async for event in session.run("write fib.py with a fib(n) function"):
            match event:
                case AssistantText(text=text):
                    print(text, end="")
                case ToolUse(summary=summary):
                    print(f"\n● {summary}")


asyncio.run(main())

The CLI and the SDK consume the same typed event stream. For headless runs, pass permission_callback= to decide what would otherwise prompt. Extensions can be passed in code (SessionOptions(extensions=[...])) and tested against a scripted model (tinyharness.testing). Subagents can be defined in code (AgentSpec) or Markdown, each on any provider's model, and conversations can be resumed from code (SessionOptions(resume="latest")). Post-turn evaluators can be passed with SessionOptions(evaluators=[...], evaluator_timeout=30.0); their bounded results are appended to the versioned trace without changing the completed conversation. See examples/ for a one-shot query, a multi-turn session, resuming, a custom tool, a permission policy with hooks, skills, subagents on different models, an extension, and a post-turn evaluator.

What's inside

Each of these in detail: docs/features.md.

How it works

 CLI (cli/) ──┐
              ├──► Session (session.py) ──► agent loop (agent/loop.py) ──► LLM (llm/client.py ─ llm/adapters/)
 SDK ─────────┘        wires components          │                           retries, model lists
                                                 ├─ compaction (agent/compaction.py)
                                                 ├─ runaway / empty-reply recovery (agent/runaway.py)
                                                 ├─ permission gate (permissions/gate.py) ── hooks
                                                 └─ tools (tools/*.py) ── workspace, sandbox + allowlist proxy
                                                      │
                                                      └─ extensions (ext.py, extensions/) add tools,
                                                         prompt sections, commands and hooks; the agents
                                                         extension's Agent / Team ──► subagents
                                                         (subagents/runner.py): the same loop, fresh
                                                         history, any provider:model

Suggested reading order:

Every prompt sent to the model is a Markdown file in tinyharness/prompts/.

Docs

• docs/features.md: everything above, in detail
• docs/configuration.md: API keys, providers, gateways, self-hosted models, where files live
• docs/extending.md: extensions, custom tools, hooks, subagents and plugins
• docs/extension-api.md: the extension API in full
• docs/skills.md: writing and sharing skills
• CHANGELOG.md and AGENTS.md (how to work on tinyharness, for people and agents)

Development

git clone https://github.com/anujdutt9/tinyharness && cd tinyharness
uv sync                   # installs dev tools too
uv run tinyharness
uv run pytest             # tests use a scripted fake LLM; no API key needed
uv run pytest --terminal  # also the screen-layout tests, in an emulated terminal (slower)
uv run ruff check . && uv run ruff format --check . && uv run mypy
uv build && uv run python scripts/check_dist.py   # build and smoke-test the package

Releasing: bump __version__ in tinyharness/version.py, add a CHANGELOG entry, then push a matching tag (git tag v0.2.0 && git push --tags). The release workflow tests, builds and publishes to PyPI.

License

Apache License 2.0.