p3 · walkthrough · the coding companion to “Pi, simply”

Say what's broken. The work runs where the code is.

This is the coding half of the Home-first proposal. Mario talks to Pi in Home. Pi picks the checkout and the machine, and the work shows up as a card. Opening a card goes one level down: the transcript, a live terminal, the diff, the files.

Underneath, every piece of work uses one list: the machines, logins and tools it may touch. A project carries its list. Everyone working in it uses all of it, and each thing on it keeps its owner's login. The screens show the list only when it matters: when it grows, while something lent is in use, and when someone asks.

Eleven screens follow Mario through one morning in pi-mono, from a flaky test to a merged fix, with Cristina joining halfway.

1 · Talk first

Home picks the place

Mario names the problem. Pi picks the checkout and the machine, and shows them as a chip he can change.

2 · One list

Work uses its project's things

A card in pi-mono uses pi-mono's machines, logins and tools, and nothing else. Whoever asks uses all of it.

3 · One level down

Detail when you open it

Cards show progress. Transcript, terminal, diff, files and git are one tap behind them, live.

4 · Ask in the moment

Narrow, visible, stoppable

A new machine or tool is asked for once, shows in the bar while in use, and stops with one tap.

Say what's broken, Pi finds the checkout

Mario names the test, not the repository. Pi says where the work goes before it starts, and the work becomes one card.

The outbox trim test flakes on CI. Can you find out why?

That test is in pi-mono. I'll work in ~/pi-mono on this Mac and run it until it fails.

Flaky outbox trim testpi-mono · this Macstarting

Tell Pi…

Recent pi-monochord-docs

The place is a chip, not a form. “pi-mono · this Mac” names the checkout and the machine. Tapping it changes either. If two checkouts match, Pi asks one short question.
The card works with pi-mono's things. pi-mono is a project, and its work uses the project's list: this Mac, GitHub, the coding tools. Underneath, the card is a session that takes its list from the project.
Home stays Mario's. Home itself may use anything Mario owns. Only work placed in pi-mono is limited to what pi-mono has.

The card is live, the detail is one level down

In Home the card shows how far the loop is and what it found. Opened, it shows the transcript and the terminal Pi is typing into.

Home

Flaky outbox trim testrun 31 of 50

Failed on run 18: expected 12 rows after trim, got 11.

Keep going, and log the commit order when it fails.

to Flaky outbox trim test

Flaky outbox trim testTell Pi…

The same card, opened

Homepi-mono · this Mac

TranscriptChangesFiles

read packages/chord/test/outbox.test.ts

loop vitest outbox.test.ts -t trim × 50

Terminal · ~/pi-monoyou can type here too

run 30/50 ✓ outbox › trim keeps unacked rows (38 ms) run 31/50 ✓ outbox › trim keeps unacked rows (41 ms) run 32/50 · logging commit order

The card shows progress, not output. A strip of runs and one line about what was found. Home never fills up with test logs.
Talking to running work is just talking. Tapping a card makes it the target of the next message. Pi says where the message went.
One level down is the real thing. The transcript, and the terminal Pi is using, live. Mario can type into it, and Pi sees what he typed.

The fix arrives as a diff

Pi found the race and changed two files. Mario reviews them like a pull request: comments on lines, then accept or ask for changes.

1 needs you

HomeFlaky outbox trim testpi-mono · this Mac

Changes

Msrc/store/outbox.ts+4 −2

Mtest/outbox.test.ts+18

Files

packages/chord

src/store

outbox.ts M

test

Git

fix/outbox-trim-floor

from main · not committed

50 of 50 runs pass with the change

packages/chord/src/store/outbox.ts

212 async trim(upTo: number) {

213 await this.store.transaction(async (tx) => {

214- const floor = this.lastSeq

214+ const floor = await tx.read(lastSeqKey)

215+ if (floor === undefined) return

MCan lastSeqKey be missing here, or is that guard dead code?

It is missing on a fresh store before the first commit. The new test covers that case.

216 for (const row of await tx.range(rowsBefore(upTo))) {

217- if (row.seq > floor) break

217+ if (row.seq >= floor) break

218 tx.delete(row.key)

AcceptAsk for changes2 files · 1 comment

Comments sit on lines. A comment is a message to Pi about that line. Pi answers next to it, and changes the diff if needed.
Accept keeps the change in the checkout. Nothing is committed or pushed yet. That comes later, and Pi asks first.
Files and git are views of the checkout, not copies. They show ~/pi-mono on this Mac as it is now, including edits Mario made himself in his editor.

A second machine, asked for once

Mario wants the full suite on slayer, his build box. slayer is not one of pi-mono's things yet, so Pi asks first, and only for pi-mono.

Home

Looks good. Run the full suite on slayer.

Use slayer for pi-mono?

Why: run the full test suite, about 9 minutes
Signed in as: mario on slayer
While added: all work in pi-mono can run there

For this workAlways for pi-monoDon't

Tell Pi…

The card, while slayer is in use

HomeFlaky outbox trim testslayer

sync fix/outbox-trim-floor → slayer:~/pi-mono

Terminal · slayer:~/pi-mono

mario@slayer:~/pi-mono$ ./test.sh ✓ packages/ai 412 passed ✓ packages/tui 388 passed ✓ packages/agent 201 passed ✗ packages/chord 1180 passed, 3 failed lease.test.ts › renews before expiry sync.test.ts › resumes after drop outbox.test.ts › batches under load

The trim test passes everywhere. Three other chord tests failed, and each passes on a rerun.

Pi asks because pi-mono's list is shared. Mario's own Home could use slayer already. pi-mono is a project, so adding slayer there is its own choice.
Narrow first. “For this work” ends when the card is done. Mario picks “Always for pi-mono”, because the suite will run there again. Underneath, it is one line added to pi-mono's list.
In use, in the bar. While a command runs on slayer, a chip with a light shows it. Tapping it shows what ran there and has a Stop button.

Three helpers, side by side

One sentence starts three pieces of work. Each gets its own copy of the code and its own place, and the results come back as one answer.

Also look at the other three flaky tests.

Three helpers, each in its own copy of pi-mono. The load test needs slayer's cores, so that one runs there.

Lease renews before expiry

worktree lease · this Mac

Fixed. The test used real time; it now uses the fake clock. 50 of 50 pass.

Sync resumes after drop

worktree sync · this Mac

Not the test. Resume can skip one frame when the drop lands mid-batch. Needs a decision.

Outbox batches under load

~/pi-mono · slayer

Run 140 of 200, no failure yet. A timeout of 2s looks too tight under load.

So far: one test fixed, one real bug in sync, one still running. Want me to fix the sync bug too, or open an issue first?

Tell Pi…

One sentence, three cards. Each helper works in its own worktree, so they never edit the same files. Each card opens to its own transcript and diff.
Helpers use the same list. They are part of the same work, so they can go only where pi-mono's list reaches. The third runs on slayer because slayer was added a moment ago.
Results come back together. Pi reads all three and answers once. The question at the end is the next decision, not a status report.

Tools that sign in

Linear is on pi-mono's list, signed in as Mario. The checkout also suggests a tool of its own, and Pi asks once whether to turn it on for this checkout.

Home

Open an issue for the sync bug and link it to the trim fix.

Linearas Mario2 steps

created PI-418 Sync resume skips a framelinked PI-412 ↔ fix/outbox-trim-floor

Done. PI-418 is in the Chord team's backlog, assigned to nobody yet.

Tell Pi…

Inside the sync card, the first time

HomeSync resumes after droppi-mono · this Mac

This checkout suggests a tool

Tool: chord-inspect: reads a store's frames and leases
From: ~/pi-mono/.pi/mcp.json
Runs: on this Mac, in ~/pi-mono only

Enable for this checkoutNot now

Tell Pi about this work…

A login belongs to its owner. Linear on pi-mono's list is Mario's Linear. Whoever asks in pi-mono, the issue says Mario made it. A second login would be a second Linear, someone else's.
A checkout's suggestion is asked once. Enabled, it runs in ~/pi-mono on this Mac and nowhere else. Helpers in other worktrees don't get it. If the file changes, Pi asks again.
Enabled means Mario's tool, on pi-mono's list. Others working in pi-mono can use it too. Someone opening the same repository elsewhere gets nothing until they enable it.

Bring Cristina into pi-mono

Inviting someone shares the project's work and its list. The card says plainly what that list holds, because she will use all of it.

Mario's Home

Add Cristina to pi-mono. She'll take the sync bug.

Invite Cristina to pi-mono

She sees: pi-mono's work and its history
She uses: this Mac, slayer, Linear and GitHub, all as you
She doesn't: your Home, or anything not in pi-mono

Invite CristinaReview the list firstNot now

Tell Pi…

pi-mono, as Cristina sees it

Homepi-monoMCAsk Pi

Sync resumes after dropfor you · PI-418

Flaky outbox trim testaccepted

Lease renews before expiryfixed

Work here uses

this Mac Mario'sslayer Mario'sLinear as MarioGitHub as Mariochord-inspect Mario'scoding tools

Sharing a project shares its list. Everyone who can ask Pi in pi-mono uses everything on it. So the invite names the list, not only the screens.
Logins stay with their owners. Cristina sees “Linear as Mario”. When she asks Pi to comment on PI-418, the comment says Mario. Her own Linear would be a second one she brings.
Home is never shared. Cristina gets pi-mono, not Mario's Home and not the other things Mario owns. “Review the list first” lets Mario take this Mac off before she joins.

Cristina lends a GPU box, for one task

Mario wants a benchmark on real hardware. Cristina has the machine. Pi asks her, in her Home, for the smallest thing that would work.

Mario, in pi-mono

Homepi-monoMC

Benchmark trim on a GPU box with the big fixture.

pi-mono has no GPU machine. Cristina has gpu-box. I've asked her to lend it.

Benchmark outbox trimwaiting for Cristina

Ask Pi in pi-mono…

Cristina's Home

1 needs you

Lend gpu-box to pi-mono?

Asked by: Mario, to benchmark outbox trim
Signed in as: cristina on gpu-box
While lent: anyone in pi-mono can run there

For this taskAlways for pi-monoDon't lend

Tell Pi…

The owner decides, in her own Home. gpu-box is Cristina's, so only she can put it on pi-mono's list. The request names who asked, why, and the login it runs as.
The narrowest choice comes first. “For this task” ends by itself when the benchmark is done; the chip leaves the bar, and the work notes when it ended.
“While lent” is the honest line. Anyone who asks Pi in pi-mono uses everything on its list, so while it is lent, Mario's messages run on her machine, as her.

Commit, push, and watch CI

Pi drafts the commit and asks before anything leaves the machine. CI comes back as a card, and a failure turns into the next piece of work.

Home, ready to push

Ship the trim and lease fixes.

Push and open a pull request?

fix(chord): read outbox floor inside the trim transaction Trim read lastSeq before the commit finished, so a concurrent commit could lose a row. Also moves the lease test to the fake clock. closes PI-412

Branch: fix/outbox-trim-floor, 2 commits
To: earendil-works/pi on GitHub, as Mario

Push and open PREdit messageNot yet

Tell Pi…

Home, twelve minutes later

1 needs you

PR #4127 · CI4 of 5 checks

check · lint and types

test · node 22, linux

test · node 24, linux

test · node 24, macos

test · node 24, windows

Windows: trim test pathpi-mono · this Mac

The new test builds a path with “/”. Fixing it on the same branch; I'll ask before pushing again.

Tell Pi…

Pi asks before anything leaves the machine. Committing in the checkout is part of the work. Pushing and opening a pull request are asked for, with the message right there to edit.
It is Mario's GitHub. The push and the pull request are signed as Mario, because GitHub on pi-mono's list is his. Had Cristina asked, it would still say Mario.
A failure is the next card. Pi watches the checks. A red one starts new work in the same checkout and on the same branch, and comes back with a fix.

What can Pi touch in pi-mono?

Mario asks instead of looking for a settings page. The answer is the real list, as it is right now, with a Stop next to each line.

What can Pi touch in pi-mono right now?

Work in pi-mono uses these, whoever asks. You and Cristina can both ask.

this Mac · works in ~/pi-mono · yoursStop

slayer · as mario · yours · since 10:05Stop

Linear · signed in as youStop

GitHub · signed in as youStop

chord-inspect · this checkout only · yoursStop

Claude · on your accountStop

Coding tools · files, terminal, helpers, gitChoose

gpu-box · Cristina's · lent for one task, ended at 11:20

Nothing else: not your Home, not your other machines.

What ran on slayer today?Make slayer for this work onlyAll settings

Tell Pi…

The answer is the list the work uses. Not a summary written for the occasion: the same list the running cards follow, with each owner and login.
Stop takes it off pi-mono's list. A command already running may finish; the next one is refused, even inside work that started before. Cristina sees Stop only on her own things.
Ended things stay visible for a while. gpu-box shows when it ended, so “did that ever end?” has an answer without a log.

A machine, opened directly

Tapping slayer anywhere opens the machine itself: its files, its terminals, its settings, and the work running on it.

Homeslayerin use

slayer

readyMario's · ssh mario@slayer.marioslab.io · Linux · 32 cores

Files · filesTerminals · terminalsSettings · machines

~/pi-mono · Pi, load test~/pi-mono · bash

Pi · Outbox batches under load mario@slayer:~/pi-mono$ npx vitest run outbox -t "batches under load" --repeat 200 run 172/200 ✓ batches under load (1.84 s) run 173/200 ✗ batches under load timed out after 2000 ms run 174/200

Working here

Outbox batches under loadpi-mono · helper · running

Full suitepi-mono · done at 10:14

Used by

your own workalways

pi-monoStop

The page is put together from pieces. Files, Terminals and Settings each come from their own plugin, as the small labels show. A remote desktop tab could be added later without touching the others.
It shows who works there. Each running piece of work on slayer, with its project. Opening one goes to its card; the terminal Pi uses is the same one Mario can type into.
Where it is used is listed, and stopped, here too. slayer is Mario's, so he can take it out of pi-mono from the machine as well as from the project.

Left out on purpose

No repository or machine picker on the way in. Pi picks; the chip shows the choice and changes it.
No prompt per command. Pi asks when pi-mono's list would grow, and before anything leaves the machine. Running tests in the checkout needs no question.
No resource panel next to every conversation. The list is shown when asked, at the moment it changes, and in the bar while something lent is in use.
No editor. Diff, files, git and terminal are views of the checkout. Editing by hand stays in Mario's editor, and Pi sees the result.

Open questions

This Mac or slayer? Proposed: where the checkout is and the last run was; ask only when both have it and the work will run long.
When a card asks, and when it acts. Proposed: ask before pushing, before anything touches someone else's machine or login, and before deleting; act on everything else in the checkout.
How much transcript by default. Some coders want the terminal open, not the card. Remember the last choice per project, or a per-person setting?
A folder, not the whole machine. The list holds a machine; ~/pi-mono is only where work sits. Should a machine on a list be narrowed to one folder?
“For this task” and a clock. Underneath, a lent thing ends at a time. Does “this task” end when the card is done, and what if the card never finishes?