@ai-matrx/coding-sessions

Drive the person's own Claude Code and Codex — on their own subscription logins, with no API keys — from AI Matrx, and take over chats they started anywhere else. A clean screen, no terminal.

• ./engine (Node) — start, follow up, stop and take over coding sessions. Wraps Paperclip's MIT driver packages (@paperclipai/adapter-claude-local, @paperclipai/adapter-codex-local, @paperclipai/adapter-utils) with every fix our 2026-09-27 spike found built in.
• ./server (Node) — the local host: HTTP + WebSocket on 127.0.0.1 only, behind a per-launch random token. Serves the screen and bridges it to the engine.
• ./react — the screen: Running · Recent · Your other chats, a live transcript rendered by @ai-matrx/chat (markdown answers, collapsible tool cards, streaming), a composer, and a New session flow. Light and dark.
• . — the pure half: the types, the provider normalizers, the projection into chat messages, and the WebSocket transport.

Run the screen

npx coding-sessions host start --port 4789
# CODING_SESSIONS_URL=http://127.0.0.1:4789/?token=…

Open the printed URL. The token is read once, kept for that tab only, and removed from the address bar. The host refuses any socket without the token or from another origin.

Use the engine directly

import { createCodingSessionsEngine } from "@ai-matrx/coding-sessions/engine";

const engine = await createCodingSessionsEngine();
engine.subscribe((event) => console.log(event)); // session · run · item (normalized, both providers)

const providers = await engine.providers();       // installed, version, signed in, subscription vs API
const others = await engine.discoverSessions();    // existing Claude Code + Codex chats on this computer

const { session, run } = await engine.start({ provider: "claude", cwd: "/path/to/repo", prompt: "Fix the flaky test" });
await engine.send(session.id, "Now add a regression test"); // queues if a run is live
await engine.stop(run!.runId);

const taken = await engine.takeover({ provider: "codex", providerSessionId: others[0].providerSessionId, cwd: others[0].cwd! });
await engine.send(taken.id, "Pick up where we left off");

Transcripts stay in the providers' own files (~/.claude/projects, ~/.codex/sessions); the engine keeps only a small index of sessions and runs in ~/.matrx/coding-sessions/index.json.

Accounts and limits. With the host's accounts port, each account keeps its own health and usage (Claude Code: from its runs' rate_limit_event; Codex: its usage probe), so a limit on one account never blocks another. When a session's account is limited and another signed-in account of the same app is free, providers() names it (continueOn) and the screen offers "Continue on "; engine.continueOnAccount(sessionId, accountId) copies the chat into that account's home, resumes it there and re-sends the stopped turn. The host's knob is the engine option switchAccount: "off" | "offer" (default "offer").

Mount the screen in your own app

import { createWebSocketTransport } from "@ai-matrx/coding-sessions";
import { CodingSessionsApp } from "@ai-matrx/coding-sessions/react";

<CodingSessionsApp transport={createWebSocketTransport({ url: "ws://127.0.0.1:4789/ws", token })} />;

A desktop shell replaces the WebSocket with IPC by implementing CodingSessionsTransport on the UI side and calling createHostBridge(engine).handle(method, args) on the other — the UI and the engine never change.

Styling: the screen uses the design system's semantic Tailwind classes. A Tailwind v4 host imports @ai-matrx/design-system/theme.css, the chat package's tokens.css and styles.css, and adds this package's dist as an @source. The page served by ./server ships all of it compiled.

What it deliberately does not do

• Tool-permission approvals. Runs bypass them (the driver default for Claude; Codex runs in its own workspace-write sandbox with network). Approvals are a later feature.
• Copy transcripts. Reading a chat reads the provider's own file; nothing is duplicated.

License

MIT. Loads Paperclip AI's MIT-licensed driver packages at run time — see NOTICE.