obsidian-vault/010 inbox/Paperclip Harness.md

type, proposed_folder, proposed_toc, proposed_tags, confidence, approved, proposed_for, created, tags, aliases, modified

type	proposed_folder	proposed_toc	proposed_tags	confidence	approved	proposed_for	created	tags	aliases	modified
note	300 areas/350 AI Pi Coding Agent	100 Table of Contents/Areas.md → AI & Coding Agent	ai-agents architecture go paperclip tuios terminal	0.76	false	45c52c2e32c3	2026-11-11 19:30	paperclip tuios go agents terminal	Paperclip Harness	2026-11-11 19:30

Paperclip Harness

A terminal control room for an AI coding factory. Paperclip runs the work; this is the surface a person uses to see it, direct it, and decide what lands.

What it is, simply

Paperclip is a control plane for AI agents: it keeps tasks, blockers, comments, approvals, runs, cost and a git worktree for every task. It has a web dashboard. This project is the same work, on a terminal, inside TUIOS: eight workspaces, each one pane, each pane a small Go program.

You look at the board, choose a task, and read it in four places: what it is, what the agent did, what changed, and what was said. You can reply to the agent, change its model or budget, give one agent a skill no other agent has, merge its work after a review, or press one key to rebuild the layout when TUIOS loses it.

Why it looks like this

flowchart TB
    P["The person on .27 or .51"] --> T["TUIOS panes on .13"]
    T --> PC["Paperclip API"]
    PC --> DB[("tasks, blockers, runs, cost")]
    PC --> AG["Pi agents"]
    AG --> WT["a git worktree per task"]
    AG --> PI["one Pi session per run"]

Three rules shaped it:

1. One owner per fact. Paperclip owns the tasks, the cost, the worktrees. The interface keeps nothing of its own except a small file saying which folder is on which machine.
2. A task is finished when the agent says so. A reviewer or ocr can refuse the change. A project check exists only as a regression check at merge time.
3. Merging is a decision. It asks first, shows the branch and the checks, takes a lock, and rolls back if the checks fail after the merge.

What was hard, and what that shows

• The API hides things. The task list does not carry blockers, so a tree that trusts it lies. The fix was to ask per task, and to write that down so nobody trusts the list again.
• Permissions are part of the design. An agent key cannot write outside a run; the person's key can. Mixing them up looked like a broken API for an afternoon.
• Another program owns the keyboard. TUIOS keeps h j k l z n and also [ ] Tab , . = ;. Tabs are switched with ( ), and a pane that stops responding is in TUIOS's window mode.
• A stale size looks like a broken interface. The panes re-ask the terminal for its size on every refresh; that fixed every "broken border" report.

What it demonstrates

Integration of a dozen systems without duplicating any of them; a single source of truth enforced in code; failure-aware design (locks, refusals, rollback, three-state health checks); terminal interface work under another program's keymap; and reporting where every claim names the command that proved it.

Diagrams and the extended collection

• Architecture map (interactive): Archify map
• Mermaid source: docs/architecture.mmd in the repository, rendered to docs/diagrams/architecture.png
• For an agent picking this up: the Outline collection Paperclip Harness holds the system overview, configuration and paths, the code map, and the agent runbook.
• Code: gitea.lab.audasmedia.com.au/sam/paperclip-harness

Where things are

• Repository: gitea.lab.audasmedia.com.au/sam/paperclip-harness
• Local: ~/paseo/projects/paperclip-harness
• Runs in: TUIOS session paperclip-harness on .13