2.0 KiB
2.0 KiB
System overview
What it is
Paperclip Harness is a terminal interface over Paperclip. Paperclip is a control plane. It keeps tasks, blockers, comments, approvals, runs, cost and a git worktree for each task. This project shows that work in a terminal, inside TUIOS, and adds the few actions a person needs.
The parts
- Paperclip on
http://127.0.0.1:3100. It owns every fact. It runs Pi agents. - TUIOS. It owns sessions, workspaces, panes and part of the keyboard.
- The Go program in
tui/. One binary. Each pane runs one screen. - Commands in
bin/. They do the work that should not be a keystroke: adopt a folder, build panes, merge one task, review one task, ask Mouse-1 one question.
The eight workspaces
| Workspace | Purpose |
|---|---|
| Shell | a prompt in the project folder, with the paths printed above it |
| Board | the state of the work, and what needs a person |
| Work | runs, diff, facts, review, run log, merge |
| Agents | who is working, on what, for how much; and their settings, skills, extensions |
| Reply | the task thread and a reply box |
| New task | the form that creates a task |
| Project | dashboard, costs, settings, adopted projects |
| Repair | health checks, live layout, rebuild log, session cleanup |
The data flow
- A person creates a task in
New task, or one already exists in Paperclip. - The person assigns it on
Board. Paperclip wakes the agent. - The agent works in its own git worktree, on its own branch.
- The agent comments and sets the status.
- The person reads the run log, the diff and the review.
- The person merges.
bin/mergerebases, checks, reviews, merges, and checks again.
What the project stores
One file per project: <folder>/.harness/harness.toml. It holds the session name, the machine,
the Paperclip project id, and the task being watched. It holds no task data.
A registry at ~/.config/paperclip-harness/projects.toml lists adopted projects, so a person can
see which folder lives where.