@catdaemon/pi-cmux 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlton Downie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @catdaemon/pi-cmux
+
+cmux status and notification integration for Pi.
+
+The extension updates cmux status when the main Pi agent starts/finishes work and sends a cmux notification when a turn completes. It also exports helper functions for other Pi extensions that need cmux notifications.

package/index.ts

@@ -0,0 +1,2 @@
+export { default } from './src/cmuxIntegration.ts'
+export * from './src/cmux.ts'

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@catdaemon/pi-cmux",
+  "version": "0.1.0",
+  "description": "cmux status and notification integration for Pi.",
+  "type": "module",
+  "keywords": ["pi-package", "pi", "cmux", "notifications"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Catdaemon/pi-extensions",
+    "directory": "packages/cmux"
+  },
+  "homepage": "https://github.com/Catdaemon/pi-extensions/tree/main/packages/cmux#readme",
+  "bugs": { "url": "https://github.com/Catdaemon/pi-extensions/issues" },
+  "pi": { "extensions": ["./index.ts"] },
+  "files": ["index.ts", "src", "README.md", "LICENSE", "package.json", "tsconfig.json"],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test src/tests/*.test.ts",
+    "pack:dry-run": "npm pack --dry-run --ignore-scripts",
+    "prepack": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}

package/src/cmux.ts

@@ -0,0 +1,147 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+type PiExecResult = {
+  stdout?: string
+  stderr?: string
+  code?: number
+  killed?: boolean
+}
+
+export type CmuxNotifyOptions = {
+  title: string
+  subtitle?: string
+  body?: string
+  workspace?: string
+  surface?: string
+  signal?: AbortSignal
+}
+
+const CMUX_TIMEOUT_MS = 3000
+
+function readString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined
+}
+
+function readNumber(value: unknown): number | undefined {
+  return typeof value === 'number' ? value : undefined
+}
+
+function readBoolean(value: unknown): boolean | undefined {
+  return typeof value === 'boolean' ? value : undefined
+}
+
+function normalizeExecResult(value: unknown): PiExecResult {
+  if (!value || typeof value !== 'object') return {}
+  return {
+    stdout: readString('stdout' in value ? value.stdout : undefined),
+    stderr: readString('stderr' in value ? value.stderr : undefined),
+    code: readNumber('code' in value ? value.code : undefined),
+    killed: readBoolean('killed' in value ? value.killed : undefined),
+  }
+}
+
+export function isCmuxEnvironment(env: NodeJS.ProcessEnv = process.env) {
+  return Boolean(env.CMUX_WORKSPACE_ID && env.CMUX_SURFACE_ID)
+}
+
+export async function runCmux(
+  pi: ExtensionAPI,
+  args: string[],
+  options: { signal?: AbortSignal; timeout?: number; requireCmuxEnv?: boolean } = {}
+) {
+  if (options.requireCmuxEnv !== false && !isCmuxEnvironment()) {
+    return { ok: false, skipped: true, reason: 'not in cmux', stdout: '', stderr: '' }
+  }
+
+  try {
+    const result = normalizeExecResult(await pi.exec('cmux', args, {
+      signal: options.signal,
+      timeout: options.timeout ?? CMUX_TIMEOUT_MS,
+    }))
+
+    const stdout = result.stdout ?? ''
+    const stderr = result.stderr ?? ''
+    const code = result.code ?? 0
+
+    return {
+      ok: code === 0 && !result.killed,
+      skipped: false,
+      code,
+      killed: Boolean(result.killed),
+      stdout,
+      stderr,
+      reason: code === 0 && !result.killed ? undefined : stderr || stdout || `cmux exited with code ${code}`,
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      skipped: false,
+      code: undefined,
+      killed: false,
+      stdout: '',
+      stderr: error instanceof Error ? error.message : String(error),
+      reason: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+export function getCmuxWorkspace(env: NodeJS.ProcessEnv = process.env) {
+  return env.CMUX_WORKSPACE_ID
+}
+
+export function getCmuxSurface(env: NodeJS.ProcessEnv = process.env) {
+  return env.CMUX_SURFACE_ID
+}
+
+export async function notifyCmux(pi: ExtensionAPI, options: CmuxNotifyOptions) {
+  const args = ['notify', '--title', options.title]
+
+  if (options.subtitle) args.push('--subtitle', options.subtitle)
+  if (options.body) args.push('--body', options.body)
+  if (options.workspace) args.push('--workspace', options.workspace)
+  if (options.surface) args.push('--surface', options.surface)
+
+  return runCmux(pi, args, { signal: options.signal })
+}
+
+export async function notifyCmuxNeedsFeedback(
+  pi: ExtensionAPI,
+  body: string,
+  options: { title?: string; subtitle?: string; signal?: AbortSignal } = {}
+) {
+  return notifyCmux(pi, {
+    title: options.title ?? 'Pi needs feedback',
+    subtitle: options.subtitle ?? 'Action required',
+    body,
+    signal: options.signal,
+  })
+}
+
+export async function notifyCmuxDone(
+  pi: ExtensionAPI,
+  body: string,
+  options: { title?: string; subtitle?: string; signal?: AbortSignal } = {}
+) {
+  return notifyCmux(pi, {
+    title: options.title ?? 'Pi',
+    subtitle: options.subtitle ?? 'Done',
+    body,
+    signal: options.signal,
+  })
+}
+
+export async function setCmuxStatus(
+  pi: ExtensionAPI,
+  key: string,
+  value: string,
+  options: { icon?: string; color?: string; signal?: AbortSignal } = {}
+) {
+  const args = ['set-status', key, value]
+  if (options.icon) args.push('--icon', options.icon)
+  if (options.color) args.push('--color', options.color)
+  return runCmux(pi, args, { signal: options.signal })
+}
+
+export async function clearCmuxStatus(pi: ExtensionAPI, key: string, options: { signal?: AbortSignal } = {}) {
+  return runCmux(pi, ['clear-status', key], { signal: options.signal })
+}

package/src/cmuxIntegration.ts

@@ -0,0 +1,123 @@
+import { join } from 'node:path'
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
+import { getAgentDir } from '@earendil-works/pi-coding-agent'
+import {
+  clearCmuxStatus,
+  getCmuxSurface,
+  getCmuxWorkspace,
+  isCmuxEnvironment,
+  notifyCmuxDone,
+  setCmuxStatus,
+} from './cmux.ts'
+
+const DEFAULT_STATUS_KEY = 'pi-agent'
+const SUBAGENT_SESSION_DIR = join(getAgentDir(), 'subagents', 'sessions')
+
+type CmuxIntegrationConfig = {
+  statusKey: string
+  notifyDone: boolean
+  includePromptPreviewInStatus: boolean
+  includeSubagents: boolean
+}
+
+function readConfig(env: NodeJS.ProcessEnv = process.env): CmuxIntegrationConfig {
+  return {
+    statusKey: env.PI_CMUX_STATUS_KEY || DEFAULT_STATUS_KEY,
+    notifyDone: env.PI_CMUX_NOTIFY_DONE !== '0',
+    includePromptPreviewInStatus: env.PI_CMUX_STATUS_PREVIEW === '1',
+    includeSubagents: env.PI_CMUX_INCLUDE_SUBAGENTS === '1',
+  }
+}
+
+function truncatePreview(text: string, limit = 140) {
+  const trimmed = text.replace(/\s+/g, ' ').trim()
+  if (trimmed.length <= limit) return trimmed
+  return `${trimmed.slice(0, limit - 3)}...`
+}
+
+function isSubagentSession(ctx: ExtensionContext) {
+  const file = ctx.sessionManager.getSessionFile()
+  return Boolean(file && file.startsWith(SUBAGENT_SESSION_DIR))
+}
+
+function isSubagentPrompt(prompt: string) {
+  return prompt.trimStart().startsWith('You are a subagent helping another pi agent.')
+}
+
+function shouldIgnoreTurn(ctx: ExtensionContext, prompt: string, config: CmuxIntegrationConfig) {
+  return !config.includeSubagents && (isSubagentSession(ctx) || isSubagentPrompt(prompt))
+}
+
+function sessionKey(ctx: ExtensionContext) {
+  return ctx.sessionManager.getSessionFile() ?? ctx.cwd
+}
+
+export default function cmuxIntegration(pi: ExtensionAPI) {
+  const activePrompts = new Map<string, string>()
+  const activeStarts = new Map<string, number>()
+  const config = readConfig()
+
+  pi.on('before_agent_start', async (event, ctx) => {
+    const key = sessionKey(ctx)
+    if (!isCmuxEnvironment() || shouldIgnoreTurn(ctx, event.prompt, config)) {
+      activePrompts.delete(key)
+      activeStarts.delete(key)
+      return undefined
+    }
+
+    const preview = truncatePreview(event.prompt)
+    activePrompts.set(key, preview)
+    activeStarts.set(key, Date.now())
+    const status = config.includePromptPreviewInStatus ? `Running: ${truncatePreview(event.prompt, 48)}` : 'Running'
+    void setCmuxStatus(pi, config.statusKey, status, { icon: 'sparkles', color: '#3b82f6', signal: ctx.signal })
+    return undefined
+  })
+
+  pi.on('agent_end', async (_event, ctx) => {
+    const key = sessionKey(ctx)
+    if (!isCmuxEnvironment() || (!config.includeSubagents && isSubagentSession(ctx))) {
+      activePrompts.delete(key)
+      activeStarts.delete(key)
+      return
+    }
+
+    const prompt = activePrompts.get(key)
+    const startedAt = activeStarts.get(key)
+    activePrompts.delete(key)
+    activeStarts.delete(key)
+
+    const elapsed = startedAt ? Math.max(1, Math.round((Date.now() - startedAt) / 1000)) : undefined
+    const idleText = elapsed ? `Idle (${elapsed}s)` : 'Idle'
+    void setCmuxStatus(pi, config.statusKey, idleText, { icon: 'check', color: '#34c759', signal: ctx.signal })
+
+    if (config.notifyDone) {
+      const body = prompt ? `Finished: ${prompt}` : 'Agent finished and is ready for your next message.'
+      void notifyCmuxDone(pi, elapsed ? `${body}\nElapsed: ${elapsed}s` : body, {
+        title: 'Pi',
+        subtitle: 'Done',
+        signal: ctx.signal,
+      })
+    }
+  })
+
+  pi.on('session_shutdown', async () => {
+    if (!isCmuxEnvironment()) return
+    void clearCmuxStatus(pi, config.statusKey)
+  })
+
+  pi.registerCommand('cmux-status', {
+    description: 'Show cmux integration status and environment wiring.',
+    handler: async (_args, ctx) => {
+      const message = [
+        `cmux: ${isCmuxEnvironment() ? 'enabled' : 'not detected'}`,
+        `workspace: ${getCmuxWorkspace() ?? '(none)'}`,
+        `surface: ${getCmuxSurface() ?? '(none)'}`,
+        `status key: ${config.statusKey}`,
+        `done notifications: ${config.notifyDone ? 'on' : 'off'}`,
+        `subagent turns: ${config.includeSubagents ? 'included' : 'ignored'}`,
+      ].join('\n')
+      if (ctx.hasUI) ctx.ui.notify(message, 'info')
+      else console.log(message)
+    },
+  })
+}

package/src/tests/smoke.test.ts

@@ -0,0 +1,15 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import cmuxIntegration, { isCmuxEnvironment } from '../../index.ts'
+
+describe('pi-cmux package', () => {
+  it('exports a Pi extension factory', () => {
+    assert.equal(typeof cmuxIntegration, 'function')
+  })
+
+  it('detects cmux environment only with workspace and surface ids', () => {
+    assert.equal(isCmuxEnvironment({}), false)
+    assert.equal(isCmuxEnvironment({ CMUX_WORKSPACE_ID: 'w' }), false)
+    assert.equal(isCmuxEnvironment({ CMUX_WORKSPACE_ID: 'w', CMUX_SURFACE_ID: 's' }), true)
+  })
+})

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node"],
+    "allowImportingTsExtensions": true
+  },
+  "include": ["index.ts", "src/**/*.ts"]
+}