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 journal 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, 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 |
| 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.
- Every sibling is optional. magi with nothing else installed is a session with three builtin tools, no model and no memory — which runs, and says so.
- 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.