nsync

nsync lets an application talk to AI agents running in Claude Code, without a human ever touching a terminal.

The agent runs where it always runs — a real Claude Code session, in a real tmux pane, with the user's own Anthropic account. nsync gives your application a way to speak to it: send it work, receive its answers, and know what it is doing right now.

┌──────────────────┐   stdio    ┌────────────┐  WebSocket  ┌──────────────┐
│  Claude Code     │◄──────────►│ src/bridge │◄───────────►│  src/server  │
│  in a tmux pane  │  (MCP)     │            │   :3210     │              │
└──────────────────┘            └────────────┘             └──────────────┘
        the agent               runs inside the             runs inside
                                agent's process             your app

The agent calls one MCP tool, sendMessage, and that call blocks until your application answers it. That is the whole protocol. An agent with nothing to do is asleep inside a blocked call — no polling, no idle loop, no tokens burned.

Working with an AI agent?

Most of the code written against nsync will be written by one, so the documentation is written for one. Hand it over with a sentence:

Read docs/index.md before writing any nsync code.

If you installed nsync rather than forking it, that is node_modules/@pixelspace/nsync/docs/index.md.

That one file is the map: it names every page and says what each is for, so your agent can pick what it needs instead of reading the repository. Say it once, at the start.

It matters more here than it would elsewhere. An agent that knows only the name writes plausible code, and plausible code against nsync ignores what send() returns, treats a missing agent as dead, and asks whether there is a hosted mode. There is not.

Try it in thirty seconds

You need macOS or Linux, tmux, Node 18+, and claude on your PATH, signed in.

node examples/scripts/ask.js "write a haiku about tmux"

One prompt in, one answer out, agent gone. Then read examples/scripts/protocol.js — 92 lines that do the same job by hand, so you can see the protocol.

The four verbs

An application needs exactly four things from nsync. Everything else — queues, forced delivery, interrupts, live model switching, telemetry — is refinement on top.

const { NsyncServer, AgentManager } = require('@pixelspace/nsync');

const server = new NsyncServer({ port: 3210 });
const manager = new AgentManager(server, {
  bridgePath: require.resolve('@pixelspace/nsync/src/bridge/server.js'),
});
await server.start();

await manager.createAgent('pixy', { model: 'sonnet', cwd: '/some/dir' });  // 1. create it

server.on('agent:ready', async (agent, exchange) => {                      // 2. hear it
  await exchange.respond({ type: 'request', text: 'do the thing' });       // 3. answer it
});

await server.inspectAgent('pixy');                                         // 4. know its state

Your first agent is this with the parts that matter filled in.

Documentation

docs/index.md is the map. It lists every page and says what each is for.

| | | |---|---| | Guides | Doing a thing: a first agent, sending to a busy one, seeing what it is doing, surviving a restart, letting agents talk to each other. | | Reference | Every method, event, state, error code and wire format. | | Concepts | The architecture, what nsync deliberately does not do, and the policies that are closed. | | Compat | The Claude Code compatibility protocol: the dependency inventory, the dated reviews, and the check that says when the next one is due. |

What is in this repository

| | | |---|---| | src/ | This is nsync. The library. | | docs/ | The documentation above. | | examples/ | scripts/ — two single-file programs, no UI: the protocol laid bare. playground/ — an Electron app that exercises everything. | | tests/ | 687 tests, including the suite that keeps the documentation matching the code. npm test. |

Requirements, and one thing that is not negotiable

• macOS or Linux
• tmux
• claude (Claude Code) on your PATH, signed in to your own account
• Node.js 18+

Every person using an nsync application needs their own Anthropic account and their own authentication. nsync never handles, stores or forwards a credential, there is no hosted mode, and it always uses the interactive terminal rather than headless mode — which is what makes subscription pricing apply instead of per-token API pricing, and is the reason the project exists.

This is not a limitation to work around. It is the shape of the product. docs/concepts/policy.md explains all three.

The record of how every decision was made lives in git history — the commit messages carry the why. If any document disagrees with the code, the code is right.

License

Apache-2.0. Decided 2026-08-24: the explicit patent grant protects the people who run nsync, not only the people who write it.