86 lines
3.2 KiB
Markdown
86 lines
3.2 KiB
Markdown
---
|
|
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`
|