#The last harness you'll ever need.

tlh (The Last Harness) is an opinionated harness built on top of Pi.

Two core ideas drive it:

• "you can outsource your thinking, but not your understanding": LLMs can, and should, provide options, help out with discovery and exploration, filling the gaps in your understanding and technical knowledge — they should not, however, be used as a replacement for understanding. Beware of cognitive debt.
• you should not be babysitting your agents: if you need to manually call tools, run commands, and so on, the harness has failed you.

It achieves this via a custom orchestration workflow — you only interface with an architect, whom you engage as a senior peer, and once you're satisfied with the discussion and plan, it takes over until everything is done. Work is pre-reviewed too, often multiple times, so that your time is not wasted in minutiae, freeing you to focus on the bigger picture.

You're also not asked to manually run commands, manage context, or anything like that. This is built-in and done for you. Every further action that you take is because you want to take it, not because you have to. You should not be finding yourself thinking eg "oh, I forgot to trigger /review". Your time is worth more.

tlh is also slow by default, and relatively token-expensive: it is designed to be used as a long-running, reliable, and predictable tool. You spend time preparing the work, and once it's off, it's off. No babysitting.

If this resonates with you, welcome aboard:

curl -fsSL https://github.com/diegopetrucci/the-last-harness/releases/latest/download/install.sh | bash -s --

The official release installer verifies SHA-256 checksums for every successfully fetched remote stage-0 support file before running stage 1. Raw source, mutable/custom refs, and local checkouts remain supported but are not release-integrity verified; see the install and recovery notes.

#Workflows

tlh has a few primary workflows/personas: architect, rush, product, bug-hunter, disabled. Each of them has different purpose, encoded with a different system prompt, available tools, and subagents. You can switch between primary agents at any time by pressing shift + tab — but I would suggest to try not to cross-contaminate the same session (start new ones!).

#The architect

As a software engineer, you will likely spend most of your time with the architect primary agent. The architect does not do any change directly, but its purpose is to help you investigate, find issues, plan the work, and so on. It is banned from making (bigger) direct changes, and it will always propose to encode the plan/work into smaller tickets.

At times, the architect might seem eager to ask you to approve the plan. Do not feel afraid to push back and continue exploring and understanding the stakes. This is your work, own it, and explore all possibilities. Also feel free to start new sessions, and treat existing ones as throwaways to get a better idea of what's going on. Rarely one is able to come up with the shape of work on the first try.

The architect has access to a few subagents, which can be divided in three big categories:

• Single-purpose, automatically-invoked ones to keep its context smaller: the librarian to check git repos, web-scout for the internet, etc.
• Core: as the agent does not write code, 1+ developer(s) are tasked to. Same for the reviewer, which avoids you having to run tools like /review yourself.
• Optional, second-opinions: the oracle, and the contrarian. The architect might suggest using them, but it will always be up to you whether to actually invoke them.

Notably, the oracle, contrarian, and reviewer prefer an opposite provider for independent second opinions. Direct Anthropic sessions try OpenAI Codex first, then xAI; direct OpenAI/Codex sessions try Anthropic first, then xAI; direct xAI sessions try Anthropic first, then OpenAI Codex. OpenRouter sessions use the same three-family vendor-aware order with the session model as a retry fallback. See docs/models.md for the full detail.

Again, the core idea: explore and plan with the architect. Double check with the oracle/contrarian. Go back and forth. This is where you, as a human, are required. Once happy, the implementation follows, until ready for your review.

A few quick-fire tips to get the most of the architect:

• If the planned work is too big, ask the architect to delegate even just one tk ticket at a time to the developer. Final-validation tickets go to the execution-only test-runner, which can run exact shell and generic MCP steps. You don't need to go all the way at all times.
• /annotate-last-message opens a simple native window where you can write comments to specific parts of the architect's last message
• /tree lets you go back and forth in the conversation tree. It's similar to Claude Code's /btw, but much, much more powerful. I often use it to explore smaller parts of the conversation, and after having done so, I return to the last "clean" message to clear up context (you can do so with or without generated summaries of your nested conversation).
• /annotate-git-diff: similar to /annotate-last-message, but for git diffs (even tickets!).
• /merge-origin-main-into-this-branch: merges the origin/main branch into the current branch.
• /rebase-this-branch-onto-origin-main: rebases the current branch onto origin/main.

#Product, rush, bug-hunter

These are smaller, laser-focused primary agents. I especially recommend rush for quicker fixes that the architect's workflow would be overkill for. product handles framing, tradeoffs, strategy, and ticket shaping — it doesn't write code. bug-hunter is read-only: reach for it when you want root cause before you've decided how to fix something.

#Disabled mode

disabled is a mode where no ad-hoc primary-role guidance is given, but the TLH tooling (subagents, extensions, etc.) is kept. Disabled mode receives no primary-role append, while each newly launched canonical minor agent still uses its own matching project append. It can also initiate an explicitly requested, freshly scoped project custom agent under the exact-root contract. I would say, frankly, if you find yourself using it a lot: either you should send me feedback to improve TLH, or TLH itself might not be a good fit.

#Everything else

#Subagents

Subagent orchestration is first-party TLH functionality: the runtime, prompts, and supervision ship in the root package, so there is no separate subagent package for you to install or pin. The imported test suites live in this repository and run in CI, but are excluded from the published package. TLH ships thirteen packaged roles: four primaries and nine bundled minors. Every bundled subagent starts a fresh child session, isolated from both the primary agent and one another, and receives only its task plus explicitly configured instructions. The reduced model-facing contract supports direct single or parallel execution in the foreground or through TLH-tracked async: true background work. toolBudget, native contact_supervisor, status/lifecycle controls, acceptance evidence, persisted contextUsage/contextPressure diagnostics, artifacts, model fallback, and timeout migration/undo details are covered in docs/subagents.md. Caller-supplied model-facing execution deadlines (root timeoutMs or public tasks[].timeoutMs) are not supported: humans own run and role policy in the isolated profile. An executable async-runner envelope/config's own root timeoutMs or a persisted plan's root timeoutMs fails closed before launch, while TLH-written per-step plan.task.timeoutMs and plan.tasks[].timeoutMs remain valid trusted role-ceiling metadata. Historical records remain readable and are not rewritten. Caller-supplied context, agent defaultContext, turn budgets, saved chains, and external pi-intercom detach request/result/control integration are not supported; TLH-tracked async work still uses a detached OS child process managed by TLH, and existing legacy artifacts are left untouched.

The shared human-owned run ceiling is execution.maxRunTimeMs in <agent-dir>/extensions/subagent/config.json (normally ~/.the-last-harness/agent/extensions/subagent/config.json): omission means 14400000 ms (4h), and the value must be a positive safe integer or false. Canonical minor role ceilings are code-owned defaults, applied before human overrides:

Human canonical-role overrides use subagents.agentOverrides.<role>.maxExecutionTimeMs in the isolated <agent-dir>/settings.json. TLH selects the project's role entry when present, otherwise the profile entry, and does not merge the two objects field-by-field; a project entry that omits maxExecutionTimeMs therefore leaves the code-owned role default in effect unless authoritative frontmatter declares the field. Trusted custom agents declare a positive-safe-integer maxExecutionTimeMs in frontmatter, or use the 14400000 ms (4h) fallback when omitted. A parallel batch has one shared deadline covering queueing and fallback/retry work, not one caller budget per task. false clears only the layer where it is set; another applicable run/role bound may still constrain execution. See docs/subagents.md for active-time continuation rules, migration/restart guidance, and rollback details.

Stable, always-available trusted project custom subagents are available to the architect (and disabled mode) when an exact file at <git-worktree-root>/.tlh/agents/custom/<UPPERCASE-SLUG>.md authorizes them. Custom-agent execution requires a persisted positive /trust decision for the validated Git worktree root; session-only or configuration-trust approvals never authorize custom agents. TLH removes generic custom-agent discovery from active-profile agents/**, global ~/.agents, project .pi/agents/** and .agents/**, configured subagents.agentDirs, installed-package/extra-directory definitions, and settings/default overrides (except an active-profile disabled: true deny-only tombstone); those definitions do not appear in TLH's custom-agent list/get or direct-dispatch inventory and cannot create or authorize a custom target. Canonical installer-managed packaged TLH roles continue loading from fixed <agent-dir>/tlh/agents/subagents/<role>.md paths; see docs/custom-subagents.md.

Projects can also provide session-scoped model and effort defaults for the packaged primary agents and bundled subagent roles in .tlh/defaults.json. Defaults use a separate, weaker configuration-trust decision: persisted /trust permits both surfaces, while an upstream/default/session approval permits only .tlh/defaults.json and never authorizes or modifies custom agents. The execution-only test-runner uses cheap low-effort defaults and can be customized like the other bundled minors through /subagent-settings or project defaults. See docs/models.md § Project model/effort defaults.

All bundled subagents:

• repo-scout for discovery
• diff-summarizer for change overviews
• developer for implementation and ticket-local validation
• test-runner for exact final-validation shell/MCP steps and repository/ticket-safe reports
• code-reviewer for review
• librarian for read-only GitHub repository research (uses gh CLI and git)
• web-scout for web research
• oracle for a deeper second opinion
• contrarian as a bundled default minor subagent for sparing adversarial stress-tests

#Direct model providers

TLH treats Anthropic, OpenAI Codex, and xAI as first-class direct providers. Its bundled xAI defaults use Grok 4.6 for primary and higher-reasoning roles and Grok 4.3 for utility roles. For xAI subscription access, use /login xai when available; OpenAI defaults intentionally use openai-codex for the Codex subscription provider. Anthropic and xAI subscription and API-key authentication share the provider IDs anthropic and xai, so Pi's stored /login credential takes precedence over the corresponding environment key (ANTHROPIC_API_KEY or XAI_API_KEY). TLH does not select among multiple simultaneous credentials, add auth storage, or mutate user credentials.

#Customisation

You can add your own skills, prompts, extensions, and packages to TLH.

User-level:

• ~/.the-last-harness/agent/skills/
• ~/.the-last-harness/agent/prompts/
• ~/.the-last-harness/agent/extensions/ (or via tlh install github-user/repo)
• ~/.claude/skills/ — TLH also discovers skills from the Anthropic Claude Code user directory

Repo settings:

• .pi/skills/
• .pi/prompts/
• .pi/extensions/
• .claude/skills/ — project-level Claude Code skills directory; on the primary agent, project trust must be granted before this root is read (see /trust)
• .tlh/agents/custom/<UPPERCASE-SLUG>.md — direct, Git-root-only project custom-agent definitions; see Project custom subagents for the exact contract and persisted-trust requirement.

After adding built-in append files, installing a package, or saving project trust, run /reload in TLH (or restart it) so those resources are picked up. Project custom-agent changes become active in a new snapshot after /reload or a new session.

#Per-agent project guidance

To give project-specific instructions to one packaged TLH role, add a plain Markdown prompt append under .tlh/agents/builtin/ using one of these exact filenames:

For each role, TLH starts at the current working directory and searches upward through the enclosing Git worktree; outside a Git worktree it checks only the current directory. Discovery is exact and non-recursive within each .tlh/agents/builtin/ directory. The nearest exact match wins. A nearer blank, invalid, or unsafe match does not fall through to a farther same-role file. Only the matching role's append is added to that packaged role's prompt. Legacy .tlh/<ROLE>.md paths are no longer read and have no fallback. Files are append-only plain Markdown: they do not replace the packaged prompt, and they do not support YAML frontmatter or model, tool, or other agent configuration. Project custom embedded agents use the separate exact-root contract in docs/custom-subagents.md, not this convention.

Example:

mkdir -p .tlh/agents/builtin
cat > .tlh/agents/builtin/ARCHITECT_PROMPT_APPEND.md <<'EOF'
Before proposing implementation work, state the important assumptions and risks.
EOF

.tlh/agents/builtin/ is not classified as a trust-requiring resource by the upstream runtime, but the persisted trust entry must contain the selected append source before TLH reads it. In TLH, run /trust, choose a persistent Trust option (not a session-only option), and save the decision. For a worktree-root append, run /trust while TLH is at that worktree root and persist the Trust decision there; trust saved only for a nested cwd does not authorize ancestor/worktree-root .tlh/agents/builtin/ files. Then run /reload or restart. Primary-agent appends are snapshotted at session start: edits and newly saved trust take effect for the primary only after that boundary, while switching primary roles selects the corresponding file from the same snapshot. Minor-agent appends are resolved when each child process starts, including foreground, parallel, async, and any resume/revival that launches a new child process. A live async resume/steer that continues the same child process keeps its session-start append snapshot; a resume/revival that starts a new child process rereads the current .tlh/agents/builtin/<ROLE>_PROMPT_APPEND.md append.

TLH refuses to read a symlinked .tlh, .tlh/agents, or .tlh/agents/builtin directory or prompt-append file, a non-regular file, or a file larger than 64 KiB. It fails closed rather than following a symlink, truncating content, or throwing; diagnostics for rejected files are internal and are not guaranteed to be user-visible. Recognized trusted files appear in the expanded startup header under Project guidance; rejected files do not appear in startup resources. If prompt appends are found without persisted trust, startup shows an actionable /trust plus /reload or restart warning without exposing their contents.

To undo the example, remove .tlh/agents/builtin/ARCHITECT_PROMPT_APPEND.md and run /reload or restart; new child launches and resume/revival actions that start a new child process stop using it, while a live async resume/steer that continues an existing child keeps its session-start snapshot. If an ancestor contains another ARCHITECT_PROMPT_APPEND.md, it becomes the nearest match, so remove that file too if you want no architect append (or leave an empty nearest file to explicitly shadow farther guidance).

This is separate from the upstream global/project APPEND_SYSTEM.md mechanism: the global file in the active isolated profile (by default ~/.the-last-harness/agent/APPEND_SYSTEM.md) and project .pi/APPEND_SYSTEM.md append general system instructions, not role-specific guidance. .tlh/agents/builtin/<ROLE>_PROMPT_APPEND.md only adds content to its matching packaged role and does not replace or reconfigure that system prompt.

#Docs dump

• Slash commands reference: docs/commands.md
• First-party subagent dispatch, supervision, migration, and undo steps: docs/subagents.md
• Project custom subagents — exact Git-root layout, persisted trust, and migration/undo rules
• TLH model defaults, thinking levels, and provider selection: docs/models.md
• Install, update, uninstall, paths, and undo steps: docs/install.md
• Common failure recovery and conservative troubleshooting: docs/troubleshooting.md
• Gnosis, tk, and TLH workflow integrations: docs/integrations.md
• Web search setup, privacy, and opt-out: docs/web-search.md
• MCP usage and caveats: docs/mcp.md
• Launch telemetry and opt-out: docs/telemetry.md
• Git commit attribution footer, setting, and toggle flow: docs/git-attribution.md
• Local testing and development: docs/local-development.md
• Release notes: CHANGELOG.md
• Maintainer release process: docs/releasing.md

#Third-party attribution

The compact live-progress display shows whimsical thinking phrases while a subagent is reasoning. The phrase pool is adapted from mitsuhiko/agent-stuff under the Apache-2.0 license. The full license text is at licenses/agent-stuff-Apache-2.0.txt.

#Bundled terminal skills

TLH packages three upstream terminal-integration skills from reproducible commit pins. The consolidated license texts and attribution notices for all packaged upstream skills are in licenses/terminal-skills.txt.

• Herdr — herdrdev/herdr, pinned to commit b99002ac99b09e00b4ca692436cb15a6b0d676f1 (herdr v0.9.0, Apache-2.0). Runtime prerequisite: the herdr binary must be on PATH, and the agent must be inside a Herdr-managed pane with HERDR_ENV=1.
• cmux CLI — manaflow-ai/cmux-skills, pinned to commit c669666f8607529a39a1f74ac0e8462e922dd13f (MIT). Runtime prerequisite: the cmux binary must be on PATH and able to reach the cmux app/socket for the requested workflow. Its scripts/reload.sh and scripts/cmux-debug-cli.sh references are only for a tagged cmux source checkout and are intentionally not part of the packaged runtime closure.
• tmux — openclaw/openclaw, pinned to commit 793669c8f6ddfad07b40009068f532832685b7d6 (MIT). Runtime prerequisite: tmux must be on PATH; the upstream skill targets Darwin and Linux, and its helper scripts require Bash and standard grep, date, and sleep utilities.

Only the runtime files directly referenced by these skills are bundled; upstream README files, AGENTS.md, and agent metadata are intentionally excluded. The optional related cmux skills named by the upstream guide are source-repository references, not runtime dependencies, and are not bundled.

#Bundled show-me skill

• show-me — humanlayer/skills, pinned to commit 6ab9013a10c28f5046f7f999549cd5328a0b30d7 (MIT).