supermux-core

Building with @supermux/core

@supermux/core runs coding-agent CLIs as sessions behind one TypeScript API: you send messages, read one normalized event stream, answer the agents' permission prompts and questions, and give them tools that are functions in your process. Each agent runs behind a small keeper process, so it can outlive your process and be re-attached.

• Exact signatures: references/api.md.
• Every event kind with its fields: references/events.md.

Install

npm i @supermux/core
npm i zod     # only to write host tools (zod 4)

• Node 22 or newer (22.18+ to run a .ts file directly, as the examples do), or Bun; ESM only. Node runs a .ts file as it is only when its TypeScript is erasable (no enum, no namespace, import type for types).
• The CLI of each agent you use, installed and logged in: claude, codex, cursor-agent, opencode, grok, agy. The library runs them with the user's own login and never logs in for you.
• TypeScript: "module" and "moduleResolution" set to "NodeNext", @types/node 22.

A first program

One turn on Claude Code and one on Codex: it prints the replies, allows each permission once and declines each question. Run it from a project folder, not your home folder: its state directory is under ~, and supermux() refuses a working directory that contains the state directory (invalid_workdir).

import { randomUUID } from "node:crypto"
import { homedir } from "node:os"
import { join } from "node:path"
import { supermux } from "@supermux/core"

// The agents by name, each with its defaults: its CLI's own asking mode, so its prompts come here.
// The state directory holds the session records and the keepers: a folder of its own, outside the folders agents work in.
const core = supermux({ stateDirectory: join(homedir(), ".supermux-demo"), agents: { claude: {}, codex: {} } })

// One observer sees the events of every session. Nothing is stored: keep what you need.
core.subscribe(event => {
  if (event.type !== "session.event") return
  const body = event.event
  if (body.kind === "assistant-message") console.log(`${body.agent}: ${body.text}`)
  // A request waits until it is answered: never leave one pending.
  const session = core.sessions.live(event.sessionId)
  if (body.kind === "permission-request") {
    const allow = body.options.find(option => option.kind === "allow_once")
    if (allow) session?.requests.respond(body.requestId, { optionId: allow.id }).catch(console.error)
    else session?.interrupt({ pending: "discard" }).catch(console.error)
  }
  if (body.kind === "user-question" && body.blocking) {
    session?.requests.respond(body.requestId, { decline: true }).catch(console.error)
  }
})

for (const agent of ["claude", "codex"]) {
  const session = await core.sessions.create({ id: randomUUID(), agent, cwd: process.cwd() })
  const receipt = await session.send({ content: [{ type: "text", text: "List the files here." }], whenBusy: "queue" })
  const completion = await receipt.completed // status "completed", "cancelled" or "failed" (with error)
  console.log(`${agent}: ${completion.status}`)
}

// Stops every agent: without it they keep running behind their keepers after this process ends.
await core.close({ agents: "shutdown" })
// expect-stdout: ^claude: completed$
// expect-stdout: ^codex: completed$