---
type: note
proposed_folder: 300 areas/350 AI Pi Coding Agent
proposed_toc: "100 Table of Contents/Areas.md → AI & Coding Agent"
proposed_tags:
  - ai-agents
  - go
  - paperclip
  - tuios
  - terminal
confidence: 0.71
approved: false
proposed_for: 82881ca0332c
created: "2026-11-11 19:30"
tags:
  - paperclip
  - tuios
  - go
  - agents
  - terminal
aliases:
  - Paperclip Harness
modified: "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

```mermaid
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.

## 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`