fix: agent commands live in the existing pairux CLI; drop the separate package

`pairux` already exists: the installers put a launcher on PATH (update,
uninstall, daemon, --version) that hands everything else to the desktop app.
The agent commands now ride that same path instead of a second npm binary
that collided with it and carried its own version.

- apps/desktop/src/main/agent-cli: login/logout/whoami/join/listen/say/who/
  status/leave, run headless by the main process (no window, no tray, no
  single-instance hand-off) and exit with the command's code.
- install.sh (macOS + Linux) and install.ps1: help lists the agent commands;
  Windows runs them in the console through a pipe instead of `start`.
- Removed packages/cli, its lockfile importer and vitest project; docs,
  README and llms.txt point at `pairux` from the installer.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: ralyodio

README.md

@@ -202,6 +202,18 @@ pairux --version      # Show installed version
 pairux --help         # Show help
 ```
 
+The same command brings an AI agent (Claude Code, moshcode, a script) into a live session as a
+labelled participant that follows and posts in the chat. See [pairux.com/docs/agents](https://pairux.com/docs/agents).
+
+```bash
+pairux login                     # Optional: label your agents as yours (browser sign-in)
+pairux join ABC123 --name Claude # Join with the session's join code
+pairux listen --json             # Follow chat and who is here; keeps the agent present
+pairux say "Tests pass"          # Post in the chat
+pairux who                       # Who is in the session
+pairux leave
+```
+
 ### Join as a Viewer (No Install Required!)
 
 Just open the session link in any modern browser. The viewer is a **Progressive Web App (PWA)** — you can install it for quick access without downloading anything.

packages/cli/src/api.ts apps/desktop/src/main/agent-cli/api.tspackages/cli/src/api.ts renamed to apps/desktop/src/main/agent-cli/api.ts

@@ -67,7 +67,7 @@ export class PairuxClient {
   private async request<T>(path: string, init: RequestInit = {}, auth = false): Promise<T> {
     const headers: Record<string, string> = {
       Accept: 'application/json',
-      'User-Agent': this.opts.userAgent ?? 'pairux-cli',
+      'User-Agent': this.opts.userAgent ?? 'pairux',
       ...(init.body ? { 'Content-Type': 'application/json' } : {}),
     };
     if (auth && this.opts.getAccessToken) {

packages/cli/src/auth.test.ts …/desktop/src/main/agent-cli/auth.test.tspackages/cli/src/auth.test.ts renamed to apps/desktop/src/main/agent-cli/auth.test.ts packages/cli/src/auth.test.ts renamed to apps/desktop/src/main/agent-cli/auth.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { listenForCallback } from './auth.js';
+import { listenForCallback } from './auth';
 
 describe('listenForCallback (real loopback socket)', () => {
   it('resolves with the code when the state matches', async () => {

packages/cli/src/auth.ts apps/desktop/src/main/agent-cli/auth.tspackages/cli/src/auth.ts renamed to apps/desktop/src/main/agent-cli/auth.ts

@@ -13,7 +13,7 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { createServer, type Server } from 'node:http';
 import { spawn } from 'node:child_process';
-import type { StoredTokens } from './config.js';
+import type { StoredTokens } from './config';
 
 export interface Pkce {
   verifier: string;

packages/cli/src/cli.test.ts …ktop/src/main/agent-cli/commands.test.tspackages/cli/src/cli.test.ts renamed to apps/desktop/src/main/agent-cli/commands.test.ts packages/cli/src/cli.test.ts renamed to apps/desktop/src/main/agent-cli/commands.test.ts

@@ -3,8 +3,8 @@ import { mkdtemp, readFile, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { beforeEach, describe, expect, it } from 'vitest';
-import { run, type Deps } from './cli.js';
-import { buildAuthorizeUrl, createPkce, needsRefresh } from './auth.js';
+import { run, type Deps } from './commands';
+import { buildAuthorizeUrl, createPkce, needsRefresh } from './auth';
 
 interface Call {
   method: string;
@@ -25,7 +25,7 @@ function fakeFetch(handler: Handler, calls: Call[]): typeof fetch {
       method: init?.method ?? 'GET',
       path: url.pathname + url.search,
       body: typeof init?.body === 'string' ? init.body : null,
-      auth: headers.Authorization ?? null,
+      auth: 'Authorization' in headers ? headers.Authorization : null,
     };
     calls.push(call);
     const { status, body } = handler(call);
@@ -64,7 +64,7 @@ const joined = {
 };
 
 beforeEach(async () => {
-  dir = await mkdtemp(join(tmpdir(), 'pairux-cli-'));
+  dir = await mkdtemp(join(tmpdir(), 'pairux-agent-'));
   out = [];
   err = [];
   calls = [];
@@ -113,7 +113,7 @@ describe('pairux join / say / leave', () => {
     );
     expect(code).toBe(0);
     expect(calls[0]).toMatchObject({ method: 'POST', path: '/api/v1/agents/join', auth: null });
-    expect(JSON.parse(calls[0]!.body!)).toEqual({
+    expect(JSON.parse(calls[0].body!)).toEqual({
       joinCode: 'ABC123',
       name: 'Claude Code',
       client: 'claude-code',
@@ -131,7 +131,7 @@ describe('pairux join / say / leave', () => {
         : { status: 404, body: { error: 'nope' } }
     );
     await (
-      await import('./config.js')
+      await import('./config')
     ).saveConfig(
       {
         tokens: {
@@ -143,7 +143,7 @@ describe('pairux join / say / leave', () => {
       d.configPath
     );
     expect(await run(['join', 'ABC123', '--name', 'Reviewer'], d)).toBe(0);
-    expect(calls[0]!.auth).toBe('Bearer pux_at_x');
+    expect(calls[0].auth).toBe('Bearer pux_at_x');
     expect(out[0]).toContain('(your agent)');
   });
 
@@ -176,7 +176,7 @@ describe('pairux join / say / leave', () => {
       method: 'POST',
       path: `/api/v1/agents/${joined.participantId}/messages`,
     });
-    expect(JSON.parse(calls[1]!.body!)).toEqual({ content: 'hello room' });
+    expect(JSON.parse(calls[1].body!)).toEqual({ content: 'hello room' });
     expect(await run(['say', 'x'.repeat(501)], d)).toBe(2);
     expect(calls).toHaveLength(2);
   });
@@ -281,7 +281,7 @@ describe('pairux listen', () => {
     expect(out[0]).toMatch(/Anthony: can you check the test\?$/);
     expect(out[1]).toBe('* Sam joined');
     // Second poll asks only for messages after the one already shown.
-    expect(calls[2]!.path).toContain(encodeURIComponent('2026-09-24T12:00:01.000Z'));
+    expect(calls[2].path).toContain(encodeURIComponent('2026-09-24T12:00:01.000Z'));
     expect((await readConfig()).agent).toMatchObject({ cursor: '2026-09-24T12:00:01.000Z' });
   });
 
@@ -305,7 +305,7 @@ describe('pairux listen', () => {
     await run(['join', 'ABC123'], d);
     out = [];
     await run(['listen', '--json', '--once'], d);
-    expect(JSON.parse(out[0]!)).toMatchObject({ type: 'message', content: 'hi' });
+    expect(JSON.parse(out[0])).toMatchObject({ type: 'message', content: 'hi' });
   });
 
   it('stops cleanly and forgets the agent when removed (410)', async () => {
@@ -390,7 +390,7 @@ describe('pairux login', () => {
       };
     });
     await (
-      await import('./config.js')
+      await import('./config')
     ).saveConfig(
       {
         tokens: {
@@ -408,7 +408,7 @@ describe('pairux login', () => {
   it('logout revokes the refresh token and drops it', async () => {
     const d = deps(() => ({ status: 200, body: {} }));
     await (
-      await import('./config.js')
+      await import('./config')
     ).saveConfig(
       {
         tokens: {
@@ -420,8 +420,8 @@ describe('pairux login', () => {
       d.configPath
     );
     expect(await run(['logout'], d)).toBe(0);
-    expect(calls[0]!.path).toBe('/api/v1/cli/revoke');
-    expect(calls[0]!.body).toBe('token=pux_rt_x');
+    expect(calls[0].path).toBe('/api/v1/cli/revoke');
+    expect(calls[0].body).toBe('token=pux_rt_x');
     expect((await readConfig()).tokens).toBeUndefined();
   });
 });

packages/cli/src/cli.ts …s/desktop/src/main/agent-cli/commands.tspackages/cli/src/cli.ts renamed to apps/desktop/src/main/agent-cli/commands.ts packages/cli/src/cli.ts renamed to apps/desktop/src/main/agent-cli/commands.ts

@@ -1,6 +1,8 @@
-#!/usr/bin/env node
 /**
- * pairux — bring an AI agent into a live PairUX session as a participant.
+ * Agent commands of the `pairux` launcher: bring an AI agent into a live
+ * PairUX session as a participant. The installed launcher hands these argv to
+ * the desktop app, whose main process runs them headless and exits (see
+ * ./index.ts), so they ship and version with the app and need no system Node.
  *
  *   pairux login                 sign in (browser, OAuth 2.1 + PKCE)
  *   pairux join ABC123 --name "Claude"
@@ -13,30 +15,20 @@
  * against a fake server without touching the network, the terminal or ~/.
  */
 import { parseArgs } from 'node:util';
-import { realpathSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import {
-  apiUrl as resolveApiUrl,
-  configPath as defaultConfigPath,
-  loadConfig,
-  saveConfig,
-  type CliConfig,
-} from './config.js';
+import { apiUrl as resolveApiUrl, loadConfig, saveConfig, type CliConfig } from './config';
 import {
   AuthError,
   buildAuthorizeUrl,
   createPkce,
   exchangeCode,
   listenForCallback,
   needsRefresh,
-  openBrowser as defaultOpenBrowser,
   randomState,
   refresh,
   revoke,
-} from './auth.js';
-import { ApiError, PairuxClient, type ChatMessage, type RosterEntry } from './api.js';
+} from './auth';
+import { ApiError, PairuxClient, type ChatMessage, type RosterEntry } from './api';
 
-export const VERSION = '0.1.0';
 const MAX_MESSAGE = 500;
 
 export interface Deps {
@@ -51,9 +43,11 @@ export interface Deps {
   /** Tests stop `listen` after N polls; production runs until 410 or Ctrl-C. */
   maxPolls?: number;
   login?: typeof listenForCallback;
+  /** The app version, for the User-Agent and `pairux version`. */
+  version?: string;
 }
 
-const HELP = `pairux ${VERSION}: bring AI agents into PairUX sessions
+export const AGENT_HELP = `Agent commands: bring AI agents into PairUX sessions
 
 Usage:
   pairux login [--no-browser]        Sign in so your agents are labelled as yours
@@ -138,7 +132,7 @@ export async function run(argv: string[], deps: Deps): Promise<number> {
     apiUrl: api,
     getAccessToken,
     fetchImpl: deps.fetchImpl,
-    userAgent: `pairux-cli/${VERSION}`,
+    userAgent: `pairux/${deps.version ?? 'unknown'}`,
   });
 
   const requireAgent = () => {
@@ -148,17 +142,16 @@ export async function run(argv: string[], deps: Deps): Promise<number> {
 
   try {
     switch (command) {
-      case undefined:
       case 'help':
       case '--help':
       case '-h':
-        deps.out(HELP);
+        deps.out(AGENT_HELP);
         return 0;
 
       case 'version':
       case '--version':
       case '-v':
-        deps.out(VERSION);
+        deps.out(deps.version ?? 'unknown');
         return 0;
 
       case 'login': {
@@ -351,7 +344,7 @@ export async function run(argv: string[], deps: Deps): Promise<number> {
           }
 
           for (const m of result.messages) emitMessage(m);
-          const last = result.messages[result.messages.length - 1];
+          const last = result.messages.at(-1);
           if (last) cursor = last.created_at;
           else cursor ??= result.serverTime;
 
@@ -405,36 +398,9 @@ export async function run(argv: string[], deps: Deps): Promise<number> {
   }
 }
 
-async function readAllStdin(): Promise<string | null> {
+export async function readAllStdin(): Promise<string | null> {
   if (process.stdin.isTTY) return null;
   const chunks: Buffer[] = [];
   for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
   return Buffer.concat(chunks).toString('utf8');
 }
-
-function isMain(): boolean {
-  if (!process.argv[1]) return false;
-  try {
-    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
-  } catch {
-    return false;
-  }
-}
-
-if (isMain()) {
-  const code = await run(process.argv.slice(2), {
-    env: process.env,
-    configPath: defaultConfigPath(),
-    fetchImpl: fetch,
-    out: (line) => {
-      process.stdout.write(line + '\n');
-    },
-    err: (line) => {
-      process.stderr.write(line + '\n');
-    },
-    openBrowser: defaultOpenBrowser,
-    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-    readStdin: readAllStdin,
-  });
-  process.exitCode = code;
-}

packages/cli/src/config.ts apps/desktop/src/main/agent-cli/config.tspackages/cli/src/config.ts renamed to apps/desktop/src/main/agent-cli/config.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import { parseAgentArgv } from './index';
+
+describe('parseAgentArgv', () => {
+  it('picks up an agent command from the packaged app argv', () => {
+    expect(
+      parseAgentArgv(['/opt/PairUX/pairux', 'join', 'ABC123', '--name', 'Claude'], true)
+    ).toEqual(['join', 'ABC123', '--name', 'Claude']);
+  });
+
+  it('skips switches a wrapper prepends (AppImage --no-sandbox)', () => {
+    expect(parseAgentArgv(['/tmp/.mount/pairux', '--no-sandbox', 'say', 'hi'], true)).toEqual([
+      'say',
+      'hi',
+    ]);
+  });
+
+  it('accounts for the app path in dev argv', () => {
+    expect(parseAgentArgv(['electron', '.', 'listen', '--json'], false)).toEqual([
+      'listen',
+      '--json',
+    ]);
+  });
+
+  it('leaves normal launches, the daemon and deep links alone', () => {
+    expect(parseAgentArgv(['/opt/PairUX/pairux'], true)).toBeNull();
+    expect(parseAgentArgv(['/opt/PairUX/pairux', 'daemon'], true)).toBeNull();
+    expect(parseAgentArgv(['/opt/PairUX/pairux', 'pairux://join/ABC123'], true)).toBeNull();
+    expect(parseAgentArgv(['/opt/PairUX/pairux', '--daemon'], true)).toBeNull();
+  });
+});

apps/desktop/src/main/agent-cli/index.test.ts

@@ -0,0 +1,57 @@
+/**
+ * `pairux login|logout|whoami|join|listen|say|who|status|leave`
+ *
+ * The installed `pairux` launcher passes any argument it does not handle
+ * itself (update, uninstall, --help, --version) straight to the app, the same
+ * way `pairux daemon` works. When the first real argument is one of these
+ * agent commands, the main process runs it headless, prints to the terminal
+ * and exits: no window, no tray, no single-instance hand-off.
+ */
+import { configPath } from './config';
+import { openBrowser } from './auth';
+import { readAllStdin, run } from './commands';
+
+export const AGENT_COMMANDS = new Set([
+  'login',
+  'logout',
+  'whoami',
+  'join',
+  'listen',
+  'say',
+  'who',
+  'status',
+  'leave',
+]);
+
+/**
+ * The agent command and its arguments, or null when the app should start
+ * normally. Packaged argv is [exe, ...args]; in dev it is [electron, '.', ...].
+ * Chromium/Electron switches (`--no-sandbox`, `--ozone-platform=...`) that a
+ * wrapper may prepend are skipped.
+ */
+export function parseAgentArgv(argv: string[], isPackaged: boolean): string[] | null {
+  const args = argv.slice(isPackaged ? 1 : 2);
+  const first = args.findIndex((a) => !a.startsWith('--'));
+  if (first === -1) return null;
+  const command = args[first];
+  if (!command || !AGENT_COMMANDS.has(command)) return null;
+  return args.slice(first);
+}
+
+export function runAgentCommand(args: string[], version: string): Promise<number> {
+  return run(args, {
+    env: process.env,
+    configPath: configPath(),
+    fetchImpl: fetch,
+    out: (line) => {
+      process.stdout.write(line + '\n');
+    },
+    err: (line) => {
+      process.stderr.write(line + '\n');
+    },
+    openBrowser,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    readStdin: readAllStdin,
+    version,
+  });
+}