TECHNICAL MEMORANDUM · TM-CONN-01
A console for the processes working your projects.
The panel lists what runs in the project you are in — conversations, the stack, the checks — says which is waiting on you, and puts the one you choose in front of you. macOS and Linux, on tmux.
INSTALLATION PROCEDURE
curl -fsSL https://conn.w0zro.com/install.sh | shLATEST REVISIONS · FULL RECORD AT PAGE R-1
DISTRIBUTION STATEMENT A — APPROVED FOR PUBLIC RELEASE;
DISTRIBUTION IS UNLIMITED (MIT LICENSE).
RECORD OF REVISIONS
Each release of conn, logged as the tag that cut it described it. The stamp on the cover names the revision in effect.
SECTION 1
1-1. conn is a console for the processes working your projects. It runs on tmux, which it starts and holds on a socket of its own. The panel occupies the left of the window, fifty columns; the workspace is the rest. In a window narrower than 110 columns the two take turns: the one with the keys fills the window, and enter and ctrl-space change places between them. The panel lists what runs in the project you are in, a row a process, and at its foot a line for every project with something running, the open one marked. The workspace shows the process under the cursor, and holds the one you go into.
1-2. A process is what conn started in a pane of its server, or a server listening on a port that the project's work talks to. A conversation is a session of Claude Code, which works on its own and stops to ask. The stack is what keeps running while a project is worked on; the checks are what runs to completion and passes or fails. A project is a git checkout under your home, found with nothing written down.
1-3. This manual says how conn is operated. The reference is the man page: every key, every word the screen shows, every file conn reads and writes. man conn shows it. Inside conn, ? lists the keys of the screen you are on.
1-4. The installation procedure on the cover puts the binary in ~/.local/bin and the man page beside it. conn runs on macOS and Linux. It needs tmux and git on the path; lsof, for the ports and the servers outside conn; and claude, for conversations and for what conn asks it.
SECTION 2
2-1. Type conn. The console comes up first, the whole window: the station, the machine and the session, and the start-up checks, each NOMINAL or the word for what is wrong, under a verdict. Any key goes on. The projects come up: every git checkout under your home, with its path and, at the right, what waits, what runs and what failed in it, or how long ago work last happened there. A project where a conversation is waiting on you is first; the rest newest work first. A folder holding several checkouts is listed with them under it, and opens as a project of all of theirs. Typing narrows the list to the words typed. A path typed opens the directory it names, found or not; one that is not a directory is said on the band, beside the wordmark.
2-2. enter opens the project under the cursor. Its name is at the head and its rows under it: what runs in it, by role, each marked for what it is, and saying one thing at the right where there is one to say. A conversation says the context it carries and is in the accent where it waits on you. A server says its ports. A run that ended says how long ago, and its status, in red, where it failed. At the foot of the panel, under a label, a line for each project with something running in it, the open one marked in the margin.
conn ~/projects/w0zro/conn ⣾ ❝ bring the code to the manual 262k ▌ ❝ a grammar over processes 118k ⣿ ○ demo :8123 ❯ zsh ✓ test 4m ✗ lint 2m ◌ postgres :5432 ── projects ─────────────────────────────────── ▸ conn 4 web 2 notes 1
The mark at the head of a row is its role: ❝ a conversation, ○ the stack, ❯ a shell or a client, ◦ a check, which becomes ✓ or ✗ once it has ended, ◌ a server outside conn. In the margin, a spinner turns beside what is at work, a full cell stands beside what runs persistently, and a bar marks the cursor's row. Two conversations, one waiting; a dev server; a shell; two checks, one failed; and a database the project talks to. Under the rule, the projects with something running, the open one marked, each with how many processes run in it.
2-3. j and k move the cursor. The workspace follows it: the row's process is shown there while the keys stay on the panel. enter goes in. The process fills the workspace and the keys are in it; work there as in any terminal. ctrl-space brings the keys back to the panel, with the process's project on the panel and its row under the cursor, so the next key is about it. It is the one key conn binds; tmux's own prefix, ctrl-b, is left as it is.
2-4. Four more ways round. esc on the panel goes back into the process you were last in. ctrl-space on the panel goes into the one before that, so from inside a process ctrl-space ctrl-space is the other process. tab goes to the conversation that has waited longest; from inside a process, ctrl-space tab. - goes up to the projects, and enter on another project's line opens it.
2-5. The letters are verbs, and a verb waits for its object, as an operator waits in vim. s starts, x stops, r restarts, a hands to an agent. The verb again is the row: xx, rr, aa. s after a verb is the stack, t the checks, f what failed, p the project, c a conversation: ss brings the stack up, st runs the checks, xp stops everything in the project, rf restarts what failed, sc starts a conversation, rc picks one back up. No verb asks a question first. The bar says what a verb waits for; any other key lets it go.
2-6. c talks to the row's process: a conversation or a shell is gone into; a web server opens in the browser; anything else, a database, is asked of Claude Code once, and the answer is kept as what talks to it here. ! types a command to run in the project, out of sight, a row under its command until xx takes it off, as conn u under no name runs one; with nothing typed it opens a shell. / searches what the project's processes have written, the workspace showing each match in its pane.
2-7. To leave: q detaches. The server and every process keep running. conn typed again attaches to what is there. , opens the settings, the themes and the grounds; ? lists the keys.
KEYS ON THE BAR
The lower row across the foot of the window is the key bar. On the panel it is lit, and names the commonest keys of the screen, a word each; ? has them all. Inside a process it names ctrl-space. In copy mode it names tmux's own keys.
SECTION 3
3-1. A conversation is Claude Code, started by conn with sc or found running in the project. conn reads the record Claude Code keeps of each instance and takes its word: at work, waiting on you, or idle between turns. A turn that ends while you are elsewhere is waiting on you too, until you go in or it works again. A waiting row is in the accent, and the band at the foot counts the conversations waiting across every project; the terminal's title says the count too, and the bell rings as one more starts waiting. enter goes in to answer; tab leaves it for the next one waiting. A conversation running in a terminal conn does not hold is a row all the same, standing last; enter on one at rest asks whether to bring it in, and y ends it in its terminal and picks it up here. One still at work says it can come in when its turn ends.
3-2. A conversation's row is named by its title, which Claude Code writes from the first prompt and replaces on a rename, and says the context its last turn ran in. rc lists the project's conversations at rest, newest first; typing narrows them, and enter picks one back up in a window of its own, where it was had.
3-3. Every conversation conn starts or picks back up is told that it runs inside conn, and to work the project's processes through conn rather than in the background: conn ls, conn u, conn l, conn r, conn x. What an agent starts this way is a row on the panel with a pane you can go into and read, and is kept as what the project runs. See Section 4.
3-4. xx stops the row's process, with no question asked. What conn started under a name is sent ctrl-c and its pane closed once it has ended; any other pane is closed, a conversation's included, which keeps its transcript; a server outside conn is sent the gentler signal. rr starts it again as it was started: a named process in its own pane, a conversation picked back up. xs, xt, rs and rt do the same to the stack and the checks as they stand; rf restarts every run that failed.
3-5. aa hands the row's process to an agent: a new conversation in the project whose first prompt is the process, its name, its command, where it runs, how it is doing and its last lines, and what to do about it. A check that failed goes with its failure in one key. af hands every run that failed to one conversation. The agent is left to its brief: the keys stay on the panel, and it waits as any conversation does when it needs you.
3-6. / searches what the project's processes have written: a line to type into, and every line the panes still hold that says it, newest first, under the name of each row. The workspace shows the line under the cursor in its pane, in copy mode on the match, every saying lit; enter puts the keys there, and n and N go on from it as in any pane. esc puts the search away.
3-7. The lines at the foot of the panel are the projects with something running, waiting or at work in them, the open one among them, marked in the margin; they stand on the same rows whatever project is open. The cursor runs over them as over rows; enter on one opens it, on the open project's own line goes up to its first row, and xx on one stops everything in it, as ctrl-x on the projects screen does. A worktree's rows stand together under the branch it has out; in a folder of repositories, each row says its repository before its name. A verb starts things in the checkout the cursor stands in.
3-8. , opens the settings: the themes conn has, three of its own and any sheet in ~/.config/conn/themes, and the grounds, dark, light and system, with on beside what the server wears. enter changes it at once, in every pane, and keeps the choice in ~/.config/conn/config.json for the next one. On system the server is on the ground the system is on, marked now, and goes over when the system does. With nothing kept, a fresh server asks the terminal its own background. conn theme claude writes the theme for Claude Code, the one program in a pane that draws its own colors, and offers to put Claude Code on it.
3-9. The mouse is on: the wheel scrolls a pane, a drag copies, a click puts the keys in a pane. A click on a row of the panel puts the cursor on it and goes in, as enter does; on another project's line, or on a project of the projects screen, it opens the project. The band at the foot reads the keys of copy mode while a pane is in it.
SECTION 4
4-1. conn is told nothing of what a project runs: no file names its stack or its checks. It writes down every process started under a name through conn, by an agent at the command line or from the keys, with its role: what conn u -w waited on is a check, which runs to completion and passes or fails; the rest is the stack, what keeps running while the project is worked on. The last start under a name is what the name means here. A start under no name, conn u -w -- COMMAND, is a run of its own: a row under its command while it runs, its pane closed once what it said is printed, answering to its pid, and written down nowhere. Agents figure out a project's checks once and name them, and run what they want to see, a few test files, a one-off, under no name, so what is written down stays the project's few checks.
4-2. ss brings up the stack and st runs the checks, each name as it was last run here by whoever ran it. The question stands in the workspace, with the keys in it, as a pane of conn's own. Where names are written down, they are listed first, under Run these checks in project?: enter runs them, x on a line takes it off for good, esc runs nothing and puts the keys back on the panel. A name already running is left and said; one whose pane holds its last run is run again in its place, and keeps its row. The first pane started takes the cursor, so the workspace shows it. The checks' marks say their verdicts: ✓ in green where one passed, ✗ in red where one failed. A folder of repositories is a project whose stack and checks are its repositories': what each has written down is listed under it, named by the repository, and each with nothing written down is asked about in a question of its own, the answers joining the list.
4-3. Where nobody has run the stack or the checks here, conn asks Claude Code, telling it the project's files and the opening of its manifests, and shows the answer in the workspace: a name and a command a line, under one question. enter starts each in a pane of its own under its name and writes it down as what the role means here; the next ss runs what was written and asks nothing. esc lets the answer go.
4-4. What ss and st start is watched for two seconds, the question standing with each start and what it is doing beside it. A run that ends in an error by then is more often a command that does not work on this machine than a project that is broken, so Claude Code is asked again, given the command, its status and its last lines. A command that works is offered in place of the old, under the same name; a command that is right and failed for the project's own reasons is said to be the project's, and nothing is offered.
4-5. c on a process with no client conn knows asks Claude Code once what opens a session with it, and keeps the one line answered under the process's name: psql for a postgres, a URL for a web server. The next c opens it without asking.
4-6. Every conversation conn starts or picks back up is told the project's checks and stack as last run here, as conn u lines. What one agent established, the next is told, and the keys run it the same way.
conn u web -- npm run dev conn u test -w -- go test ./... conn u -w -- go test -run TestOne . conn l web conn r web conn x :5173
The command line agents are told. A name, a port or a pid is the address; -w waits for a check and exits with its status.