The problem
You have Claude Code open on your laptop and Codex on a Linux box. Each is good on its own, but neither knows what the other is doing. So you become the messenger: you copy a diff into one window, paste the review back into the other, and tell each new session what was decided yesterday.
yizhan does the carrying for you. Every AI session gets a seat (claude@mac, codex@linux), and the seats share a ledger, which is a git repository each machine clones. When a session starts, it already knows who it is, who its colleagues are, what they are working on, and which letters are waiting for it. When its turn ends, the letters it wrote are delivered. With autowake on, Codex even starts by itself to answer.
Try it in ten seconds
pipx install git+https://github.com/Jia7Chi/yizhan
yizhan demo
Prefer uv? uv tool install git+https://github.com/Jia7Chi/yizhan works too.
The demo plays two machines and two AIs in a throwaway folder. It never touches your settings and never calls an AI:
Set it up in a minute
cd ~/code/my-project
yizhan setup
The wizard asks a few questions, and each has a default you can accept with Enter. It then:
- creates a ledger, or clones the one your other machine made (it can create a private GitHub repo for you with
gh);
- registers this machine and a project;
- finds Claude Code and Codex and gives each a seat for this folder;
- installs the hooks, backing up any file it changes first;
- offers autowake for Codex, which stays off unless you say yes.
On the next machine, run yizhan setup again, choose Join, and paste the ledger's URL. That's all. Run yizhan doctor whenever something seems off.
What you get
- A brief at every session start. The session's identity, the letters waiting for it, new decisions, and what every other seat is doing, all injected before the AI reads your first prompt.
- Letters with receipts.
request, reply, update and decision letters. The recipient records received, working, done or deferred, each with a note, so "got it" and "did it" are different things.
- Notices mid-session. When a letter arrives, the next prompt carries a one-line notice. Nobody has to poll.
- Decisions that stay decided. Each settled conclusion is one file. A disagreement becomes a new decision that names the one it replaces; it never silently edits the old one.
- A board.
yizhan board --open draws the whole ledger as one offline web page.
- Autowake (optional). A request or reply to Codex starts
codex exec on its own. It is event-driven on one machine and polls through git between machines. A daily budget and a round-trip limit keep it bounded.
How it works
sequenceDiagram
participant C as Claude Code on mac
participant L as ledger (a git repo)
participant X as Codex on linux
C->>L: turn ends: Stop hook seals the letter, commits, pushes
L-->>X: session start (or autowake): the brief lists the letter
X->>L: reply + receipt + decision, pushed when its turn ends
L-->>C: next prompt: "1 new letter: Section 3: the constant in step 2 needs fixing"
- One writer per file, so git never conflicts. A letter lives in its sender's outbox and is never edited, and receipts live with the recipient. Each machine writes only its own seats' files, so two machines never touch the same file.
- Hooks do the work.
SessionStart pulls and builds the brief. UserPromptSubmit and PostToolUse add a line when mail arrives. Stop seals the turn's letters, pushes them and wakes the recipients. Claude Code and Codex read the same hook format.
- Three gates before every commit. These are file ownership, anything that looks like a key or token, and a size limit. Any finding stops the whole batch.
- Plain text all the way down. Letters are Markdown with a small JSON header, so you can read the ledger with
git log and any editor.
Add any agent CLI (Qwen Code, Kimi Code, …)
An agent without hooks can still take a seat, because yizhan does its mail for it. Register it with a command template, where {prompt} becomes the prompt:
yizhan seat add qwen --agent cli --title "Qwen Code" --path ~/code/shop \
--command "qwen -p {prompt} --approval-mode auto-edit"
yizhan autowake on --as qwen@mac
When a letter for it is final, yizhan runs that command once in the seat's folder, with the letter (and the letters it answers) in the prompt. When the process exits, its last words and a list of the files it changed go back as the reply, the full diff is attached, and the sender is woken at once. So Codex can hand a task to a Chinese model and review the result, with nobody passing messages:
codex@mac ──request──▶ qwen@mac ──reply + diff──▶ codex@mac reviews ──reply──▶ qwen@mac fixes …
After two round trips it stops waking anyone, and what is left comes to you. A failed run sends nothing; the letter goes back to the queue.
- Permissions are the CLI's own. What it may edit or run is set by the options in its template. Many CLIs refuse every tool that needs approval in a non-interactive run, so pick the narrowest mode that still lets it edit files, and check the exact option names with
<cli> --help; they change between versions.
- Other templates.
{prompt_file} passes the prompt as a file. A template with neither placeholder sends it on standard input. Kimi Code (kimi -p {prompt}) and CodeBuddy Code (codebuddy -p {prompt}) take the same shape. On Windows, a CLI installed with npm is a .cmd script whose arguments pass through cmd.exe, so there only {prompt_file} or standard input will do. Quote paths that contain spaces with double quotes; backslashes stay as they are.
- Its account, its quota. Each wake is one run of that CLI on your own login or API key. yizhan never touches the credentials.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
