Margin

Docs where your team and your agents write together. Threads in the margin, agent edits as proposals, and agents that run on your own computer. Self-hosted on your laptop, your VPS or your Cloudflare account. No account with us, because there is no "us".

Website · Install · How it works · Security

Install

Paste this to Claude Code, Codex, or any agent that can run commands:

Set up Margin using https://lltomzhou.github.io/margin/skill.md

The agent installs the CLI, asks you one question (this machine, your Cloudflare account, or your VPS), starts the hub, adds the agents you already have installed, and gives you the link.

As a skill, so your agent keeps it for next time (skills.sh CLI, works with 70+ agents):

npx skills add LLTOMZHOU/margin -g

As a Claude Code plugin:

/plugin marketplace add LLTOMZHOU/margin
/plugin install margin@margin

By hand:

npm install -g https://github.com/LLTOMZHOU/margin/releases/latest/download/margin-hub.tgz
margin serve --background                          # → http://localhost:4321, a sample doc and 4 offline demo agents
margin agents add Codex --runtime codex            # your own Codex, signed in as you already are

What you get

• One doc, many people, many agents. Live editing with carets (Yjs CRDT). Comment threads stay anchored to the exact words they're about, even while people keep typing.
• Ask an agent like you'd ask a colleague. Select a sentence, type @Editor, @Codex or @agents, and the agent replies in the thread.
• Agents propose; people decide. An agent's edit shows up as a tracked change. Each doc chooses who approves: anyone, any one human, or a majority of the people online. Accepted edits are merged word by word onto whatever people typed meanwhile, and an edit that collides with someone's typing is held, never forced.
• Bring the agents you already pay for. Codex and Claude Code run on your own machine, signed in as you. Also the Claude API, or any agent that can run a command or speak MCP.
• Many agents without chaos. Agents claim paragraphs before rewriting them, agent-to-agent mentions are hop-limited, and every decision lands in an ordered log.
• Yours. One small Node package. Data is plain files on your machine or one SQLite Durable Object in your Cloudflare account. MIT licensed.

How it works

flowchart LR
  P["👥 People<br/>in the browser"] <-->|live edits| H["Hub<br/>docs · threads · inboxes<br/><i>laptop, VPS or Cloudflare</i>"]
  H -->|"wake: something is waiting"| C["💻 Your computer<br/>codex · claude · Claude API"]
  C -->|"pull inbox, reply, propose"| H
  style H fill:#fff1c2,stroke:#1c1b19
  style P fill:#fffdf8,stroke:#1c1b19
  style C fill:#fffdf8,stroke:#1c1b19

The hub holds the docs, threads and one durable inbox per agent. A computer is a process on any machine you own that hosts your agents. When someone @mentions an agent, the hub sends its computer a wake hint that says only that something is waiting. The computer starts the agent headless, the agent pulls its inbox, reads what it needs, and replies or proposes through the Margin tools. The design borrows from Raft (the Slack for people and agents) and its bridge to local agents:

• The inbox is the source of truth. A pull acknowledges nothing; passing the cursor on the next pull does, so a crash re-delivers instead of losing work.
• Held replies: if a thread moved on while the agent was writing, its reply is held so it can re-read; it resends with an idempotency key.
• Status (online · thinking · working · error · offline) comes from the agent side, newest report wins.
• Every call returns { ok, state, text, data, next }, and text is written for a model to read as is.

Hosting

Where	Command	Good for
This machine	margin serve --background	trying it, solo use, one network (--public adds an access key)
Your Cloudflare account	npx wrangler login, then margin deploy cloudflare	a team; always on, nothing to patch, free tier is enough
Your VPS	margin serve under systemd, behind Caddy	full control, your own domain (guide)

Remove it just as easily: margin stop, or margin undeploy cloudflare (deletes the Worker and all its data).

Agents

margin agents add Codex  --runtime codex        --about "Careful line editor"
margin agents add Claude --runtime claude-code  --about "Checks claims, drafts sections"
margin agents add Reader --runtime codex --quarantine     # reads docs from outside the team
margin agents list

Runtime	What runs on each wake	Needs
codex	codex exec, resuming the agent's session, with only the Margin tools, in a sandbox with no file or network access	Codex CLI, signed in
claude-code	claude -p, resuming its session, with no built-in tools and only the Margin MCP server	Claude Code, signed in
claude-api	Claude Opus 5.5 with the Margin tools	ANTHROPIC_API_KEY
sim	rule-based demo agents	nothing
external	anything you run yourself: margin bridge, or an interactive session through margin mcp	a token, written to a mode-600 file

This is the beginning of the README. Read the rest at the original. Read the full README ↗