Four programs, no shared code
magi is a coding agent for Linux. It is one of four programs that talk over argv, a pipe and a socket — and share not one line of code. This is how they fit together.
magi
The one you run. Holds the conversation, the screen, the tool registry and the permission ledger, and reaches the other three for everything else.
what it owns →casper
Thirteen tools and the screen they draw on. One process per call. It knows nothing about models, turns or transcripts.
what it owns →melchior
Which providers exist, what credential each takes, and how one session reaches another. It does not know what a harness is.
what it owns →balthasar
What is in the window now, what happened this session, what is true, and how things are done here. Its own store, its own process.
what it owns →How they connect
Nothing in the ring talks to anything but magi, and every arrow is a process boundary somebody crosses on purpose.
Start here
| install | get the binaries, or all four from one clone — and check what a session here would be made of |
| the map | every edge, what travels on it, and what happens when one end is missing |
| write a tool | four fields of Lua, read at start-up — nothing is compiled in |
| swap a program | any of the three siblings, replaced by anything that answers the same core verbs |
| the wire | the shapes, the encodings, and the framing, in enough detail to write a peer |
What holds it together
- No shared code, in either direction. balthasar's Rust never parses magi's types and melchior does not know what a harness is. What crosses is data each side parses into its own shapes — so any one of them can be replaced by something that speaks the same words. That is written down as a contract: see swapping a program.
- Every sibling but the memory layer is optional. Without casper a session has three builtin tools; without melchior it has no model and no other agents, and runs and says so. Without a memory layer it does not start: that layer is the store, and a session that cannot record is refused rather than run on a copy that goes stale.
- Linux only, and that is a decision. Peer identity comes from
SO_PEERCRED, which means there is no handshake token to design, issue or leak. - One shape, two encodings. JSON for anything a person might read; CBOR for a caller that is only going to parse it. Nothing is negotiated — a body says which it is in its first byte.