46 lines
2.0 KiB
Markdown
46 lines
2.0 KiB
Markdown
# 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
|
|
|
|
1. A person creates a task in `New task`, or one already exists in Paperclip.
|
|
2. The person assigns it on `Board`. Paperclip wakes the agent.
|
|
3. The agent works in its own git worktree, on its own branch.
|
|
4. The agent comments and sets the status.
|
|
5. The person reads the run log, the diff and the review.
|
|
6. The person merges. `bin/merge` rebases, 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.
|