Tilth

Prepare the ground, let the agent grow the work.

A minimal long-running agent harness against an OpenAI-compatible LLM endpoint. Tested today against OpenRouter; the OpenAI SDK underneath means other OpenAI-flavour gateways should work, but support for them is on the roadmap rather than validated. Built to learn (and demonstrate) the Brain/Hands/Session split, the Ralph loop, and the four memory channels described in Addy Osmani's long-running agents, agent harness engineering, and self-improving agents posts.

Audience: This is an active research project for my work in Altered Craft. I do activly use it for real work, so I would advise it for single-dev / few-dev teams who want to understand what a long-running agent harness actually does. That is today (May-2026), in the future, we shall see.

Target run: I test with 10-60 minutes of autonomous work against an open model (default deepseek/deepseek-v4-pro on OpenRouter). Completing a task list against a small project on a per-session git worktree.

For the full product story — the Brain/Hands/Session split in detail, the four memory channels, the two loops, token recording and enforcement, the agent-visibility boundary, and the safety guards — see the docs site. This README is the elevator pitch.

Quickstart

git clone git@github.com:AlteredCraft/tilth.git
cd tilth
uv sync
cp .env.example .env
# edit .env — TILTH_BASE_URL, TILTH_API_KEY, TILTH_WORKER_MODEL are all required
# (Tilth refuses to start without them so a misconfigured run can't silently
# fall back to a provider/model your account doesn't have)

Run the demo against a small todo-CLI workspace (a tiny Python project with an AGENTS.md and an empty tests/). Tilth's task list and matching tests come from an interview the harness runs against your code:

git clone git@github.com:AlteredCraft/tilth-demo-todo-cli.git tilth-demo
uv run tilth prep-feature ./tilth-demo   # interview, produce the seed
uv run tilth run          ./tilth-demo   # run the seeded session

For tested provider/model combinations, the full TILTH_* env-var table, the resume / reset / visualize subcommands, and the honest guide to using Tilth on your own non-demo project, see the docs.

Working with the codebase

# Lint
.venv/bin/python -m ruff check tilth/

# Tests
.venv/bin/python -m pytest

# Docs — live preview at http://127.0.0.1:8000
uv run --extra docs mkdocs serve

# Docs — strict build (the CI gate; catches broken nav refs, missing files, dead links)
uv run --extra docs mkdocs build --strict --site-dir /tmp/tilth-site

See CLAUDE.md for repo conventions and the architecture invariants worth preserving when editing the harness itself.