parallel-codex-tui 0.1.0

package/.parallel-codex/config.example.toml

@@ -0,0 +1,62 @@
+[router]
+defaultMode = "auto"
+
+[router.codex]
+command = "codex"
+args = ["exec", "--skip-git-repo-check", "--sandbox", "workspace-write", "--color", "never", "-"]
+timeoutMs = 120000
+fallback = "complex"
+
+[workers.codex]
+command = "codex"
+args = ["exec", "--skip-git-repo-check", "--sandbox", "workspace-write", "--color", "never", "-"]
+firstOutputTimeoutMs = 120000
+
+[workers.codex.interactive]
+command = "codex"
+args = ["resume", "{sessionId}"]
+
+[workers.codex.nativeSession]
+fallback = "new"
+
+[workers.claude]
+command = "claude"
+args = ["--print", "--permission-mode", "acceptEdits", "--output-format", "text"]
+firstOutputTimeoutMs = 120000
+
+[workers.claude.interactive]
+command = "claude"
+args = ["--resume", "{sessionId}"]
+
+[workers.claude.nativeSession]
+fallback = "new"
+
+[workers.mock]
+command = "mock"
+args = []
+
+[pairing]
+main = "claude"
+judge = "codex"
+actor = "codex"
+critic = "codex"
+
+[roles.main]
+title = "Main"
+instructions = ["Answer simple chat and status questions directly."]
+
+[roles.judge]
+title = "Judge"
+instructions = ["Clarify requirements and write task files. Do not implement code."]
+
+[roles.actor]
+title = "Actor"
+instructions = ["Read Judge files, implement the requested change, and record your work."]
+
+[roles.critic]
+title = "Critic"
+instructions = ["Review Actor work against Judge requirements. Lead with blocking findings."]
+
+[ui]
+showStatusBar = true
+autoOpenFailedWorker = true

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 parallel-codex-tui contributors
+
+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,150 @@
+# parallel-codex-tui
+
+A standalone TypeScript TUI wrapper for routed parallel coding workflows. It keeps a main chat open while Codex routes larger tasks into Judge, Actor, and Critic workers that can write prompts, logs, session metadata, and outputs to disk.
+
+## Requirements
+
+- Node.js 22.5+.
+- Codex CLI available as `codex` for Codex routing and Codex workers.
+- Claude CLI available as `claude` only when you configure Claude workers.
+- A project workspace you are comfortable letting configured workers edit.
+
+## Install
+
+```bash
+npm install -g parallel-codex-tui
+```
+
+Run it against the project you want the workers to operate on:
+
+```bash
+cd /path/to/project
+parallel-codex-tui --init
+parallel-codex-tui --doctor
+parallel-codex-tui --workspace /path/to/project
+```
+
+From a source checkout, install dependencies and link the local binary:
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+For development without linking, run:
+
+```bash
+npm run dev -- --workspace /path/to/project
+```
+
+Check available flags or the installed version without starting the TUI:
+
+```bash
+parallel-codex-tui --help
+parallel-codex-tui --doctor
+parallel-codex-tui --version
+```
+
+## Quick Start
+
+Create a local config in the app root:
+
+```bash
+parallel-codex-tui --init
+parallel-codex-tui --doctor
+```
+
+From a source checkout, you can also copy the public example:
+
+```bash
+cp .parallel-codex/config.example.toml .parallel-codex/config.toml
+```
+
+For deterministic local testing without real agent CLIs, set all roles to mock workers in `.parallel-codex/config.toml`:
+
+```toml
+[pairing]
+judge = "mock"
+actor = "mock"
+critic = "mock"
+```
+
+Then start the TUI:
+
+```bash
+parallel-codex-tui --workspace /path/to/project
+```
+
+## Behavior
+
+- Requests are routed by Codex by default, with a configured simple/complex fallback if the router process fails.
+- Simple requests stay in the main TUI flow and do not create Judge, Actor, or Critic workers.
+- Complex requests create a session under `.parallel-codex/sessions/`.
+- Complex requests run Judge -> Actor -> Critic.
+- Worker prompts, logs, status, and outputs are written to disk.
+- The bottom status line shows the active task state.
+
+## Router
+
+Codex routing is enabled by default:
+
+```toml
+[router]
+defaultMode = "auto"
+
+[router.codex]
+command = "codex"
+args = ["exec", "--skip-git-repo-check", "--sandbox", "workspace-write", "--color", "never", "-"]
+timeoutMs = 120000
+fallback = "complex"
+```
+
+Set `defaultMode = "simple"` / `defaultMode = "complex"` to force one path. In `auto` mode, routing is semantic through Codex. If the router process fails or returns invalid JSON, `fallback = "simple"` or `fallback = "complex"` decides the path; there is no keyword-only router.
+
+## Mock Mode
+
+For deterministic local testing, use this pairing in `.parallel-codex/config.toml`:
+
+```toml
+[pairing]
+judge = "mock"
+actor = "mock"
+critic = "mock"
+```
+
+## Real Worker Mode
+
+Configure Codex and Claude commands in `.parallel-codex/config.toml`:
+
+```toml
+[workers.codex]
+command = "codex"
+args = ["exec", "--skip-git-repo-check", "--sandbox", "workspace-write", "--color", "never", "-"]
+
+[workers.codex.interactive]
+command = "codex"
+args = ["resume", "{sessionId}"]
+
+[workers.claude]
+command = "claude"
+args = ["--print", "--permission-mode", "acceptEdits", "--output-format", "text"]
+
+[workers.claude.interactive]
+command = "claude"
+args = ["--resume", "{sessionId}"]
+```
+
+Keep `[router.codex]` on `workspace-write`; routing only classifies requests and does not need host-level access. If a trusted local project needs Docker, OrbStack, or other host services, opt into broader worker permissions in your private `.parallel-codex/config.toml` rather than committing them.
+
+The process adapter sends each role prompt to stdin and records stdout/stderr in `output.log`.
+
+While viewing a worker log, press `Ctrl+O` to attach to the worker's native session inside `parallel-codex-tui`. Native attach runs through a PTY, so full-screen CLIs such as `codex resume {sessionId}` receive a real terminal instead of pipe stdin. Input is forwarded to the configured interactive command and output is shown in the native attach panel. Press `Ctrl+]` to detach and return to worker logs; `Ctrl+C` is forwarded to the native agent while attached. In chat and worker-log views, press `Ctrl+C` to exit the outer TUI.
+
+If a native resume fails because the underlying CLI reports that its context window is full, configure `fallback = "new"` under `[workers.<engine>.nativeSession]`. The old native session is archived as `native-session.retired.json`, removed from active use, and the worker is retried once with the normal fresh-session command.
+
+## Publishing Hygiene
+
+- `.parallel-codex/config.toml` is local-only and ignored.
+- `.parallel-codex/sessions/` contains task prompts, logs, native session ids, and worker output; never commit it.
+- `docs/superpowers/` contains internal planning notes and is ignored for public releases.

package/dist/bootstrap.js

@@ -0,0 +1,25 @@
+import { loadConfig } from "./core/config.js";
+import { SessionIndex } from "./core/session-index.js";
+import { SessionManager } from "./core/session-manager.js";
+import { Orchestrator } from "./orchestrator/orchestrator.js";
+import { createWorkerRegistry } from "./workers/registry.js";
+export async function createRuntime(appRoot, workspaceRoot = appRoot) {
+    const config = await loadConfig(appRoot);
+    const index = await SessionIndex.open(workspaceRoot, config.dataDir);
+    await index.rebuildFromFiles();
+    const sessions = new SessionManager({
+        projectRoot: workspaceRoot,
+        dataDir: config.dataDir,
+        index
+    });
+    const workers = createWorkerRegistry(config);
+    const orchestrator = new Orchestrator(config, sessions, workers);
+    return {
+        config,
+        workspaceRoot,
+        index,
+        sessions,
+        workers,
+        orchestrator
+    };
+}

package/dist/cli-args.js

@@ -0,0 +1,26 @@
+import { resolve } from "node:path";
+export function parseCliArgs(args, cwd) {
+    const appRootFlagIndex = args.findIndex((arg) => arg === "--app-root");
+    const workspaceFlagIndex = args.findIndex((arg) => arg === "--workspace" || arg === "-w");
+    const taskFlagIndex = args.findIndex((arg) => arg === "--task" || arg === "-t");
+    const doctor = args.includes("--doctor");
+    const help = args.includes("--help") || args.includes("-h");
+    const init = args.includes("--init");
+    const version = args.includes("--version") || args.includes("-v");
+    const appRoot = appRootFlagIndex >= 0 && args[appRootFlagIndex + 1]
+        ? resolve(cwd, args[appRootFlagIndex + 1])
+        : cwd;
+    const workspaceRoot = workspaceFlagIndex >= 0 && args[workspaceFlagIndex + 1]
+        ? resolve(cwd, args[workspaceFlagIndex + 1])
+        : cwd;
+    const taskId = taskFlagIndex >= 0 && args[taskFlagIndex + 1] ? args[taskFlagIndex + 1] : null;
+    return {
+        appRoot,
+        doctor,
+        help,
+        init,
+        workspaceRoot,
+        taskId,
+        version
+    };
+}

package/dist/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from "ink";
+import { parseCliArgs } from "./cli-args.js";
+import { createRuntime } from "./bootstrap.js";
+import { configPath, writeDefaultConfig } from "./core/config.js";
+import { pathExists } from "./core/file-store.js";
+import { runDoctor } from "./doctor.js";
+import { App } from "./tui/App.js";
+import { version } from "./version.js";
+const helpText = `Usage: parallel-codex-tui [options]
+
+Options:
+  -w, --workspace <path>  Project workspace for worker sessions and edits
+      --app-root <path>   App root for configuration lookup
+  -t, --task <id>         Open an existing task session
+      --init              Write .parallel-codex/config.toml if missing
+      --doctor            Check local configuration and agent commands
+  -v, --version           Print the current version
+  -h, --help              Print this help message`;
+const cliArgs = parseCliArgs(process.argv.slice(2), process.cwd());
+const localConfigPath = configPath(cliArgs.appRoot);
+if (cliArgs.help) {
+    console.log(helpText);
+}
+else if (cliArgs.version) {
+    console.log(`parallel-codex-tui ${version}`);
+}
+else if (cliArgs.doctor) {
+    const result = await runDoctor(cliArgs.appRoot, cliArgs.workspaceRoot);
+    process.stdout.write(result.text);
+    process.exitCode = result.ok ? 0 : 1;
+}
+else if (cliArgs.init) {
+    if (await pathExists(localConfigPath)) {
+        console.log(`Config already exists: ${localConfigPath}`);
+    }
+    else {
+        await writeDefaultConfig(cliArgs.appRoot);
+        console.log(`Wrote ${localConfigPath}`);
+    }
+}
+else {
+    const runtime = await createRuntime(cliArgs.appRoot, cliArgs.workspaceRoot);
+    const latestTask = await runtime.sessions.latestTask();
+    const initialTaskId = cliArgs.taskId ?? latestTask?.id ?? null;
+    render(_jsx(App, { config: runtime.config, orchestrator: runtime.orchestrator, cwd: runtime.workspaceRoot, initialTaskId: initialTaskId }), { exitOnCtrlC: false });
+}

package/dist/core/config.js

@@ -0,0 +1,304 @@
+import { parse, stringify } from "@iarna/toml";
+import { join } from "node:path";
+import { z } from "zod";
+import { pathExists, readTextIfExists, writeText } from "./file-store.js";
+const NativeSessionConfigSchema = z.object({
+    enabled: z.boolean().default(true),
+    resumeArgs: z.array(z.string()).default([]),
+    detectSessionId: z.boolean().default(true),
+    fallback: z.enum(["fail", "new"]).default("fail")
+});
+const WorkerModelConfigSchema = z.object({
+    name: z.string().default(""),
+    provider: z.string().default(""),
+    args: z.array(z.string()).default([]),
+    env: z.record(z.string()).default({})
+});
+const InteractiveCommandSchema = z.object({
+    command: z.string().min(1),
+    args: z.array(z.string()).default([])
+});
+const RolePromptConfigSchema = z.object({
+    title: z.string().min(1),
+    instructions: z.array(z.string()).default([])
+});
+const CodexRouterConfigSchema = z.object({
+    command: z.string().min(1).default("codex"),
+    args: z.array(z.string()).default(["exec", "--skip-git-repo-check", "--sandbox", "workspace-write", "--color", "never", "-"]),
+    timeoutMs: z.number().int().positive().default(120000),
+    fallback: z.enum(["simple", "complex"]).default("complex")
+});
+const WorkerCommandSchema = z.object({
+    command: z.string().min(1),
+    args: z.array(z.string()).default([]),
+    timeoutMs: z.number().int().positive().optional(),
+    idleTimeoutMs: z.number().int().positive().optional(),
+    firstOutputTimeoutMs: z.number().int().positive().optional(),
+    model: WorkerModelConfigSchema.default({}),
+    nativeSession: NativeSessionConfigSchema,
+    interactive: InteractiveCommandSchema
+});
+const AppConfigSchema = z.object({
+    projectRoot: z.string().min(1),
+    dataDir: z.string().min(1),
+    router: z.object({
+        defaultMode: z.enum(["auto", "simple", "complex"]),
+        codex: CodexRouterConfigSchema.default({})
+    }),
+    workers: z.object({
+        codex: WorkerCommandSchema,
+        claude: WorkerCommandSchema,
+        mock: WorkerCommandSchema
+    }),
+    pairing: z.object({
+        main: z.enum(["codex", "claude", "mock"]),
+        judge: z.enum(["codex", "claude", "mock"]),
+        actor: z.enum(["codex", "claude", "mock"]),
+        critic: z.enum(["codex", "claude", "mock"])
+    }),
+    roles: z.object({
+        main: RolePromptConfigSchema,
+        judge: RolePromptConfigSchema,
+        actor: RolePromptConfigSchema,
+        critic: RolePromptConfigSchema
+    }),
+    ui: z.object({
+        showStatusBar: z.boolean(),
+        autoOpenFailedWorker: z.boolean()
+    })
+});
+export function defaultConfig(projectRoot) {
+    return {
+        projectRoot,
+        dataDir: ".parallel-codex",
+        router: {
+            defaultMode: "auto",
+            codex: {
+                command: "codex",
+                args: ["exec", "--skip-git-repo-check", "--sandbox", "workspace-write", "--color", "never", "-"],
+                timeoutMs: 120000,
+                fallback: "complex"
+            }
+        },
+        workers: {
+            codex: {
+                command: "codex",
+                args: ["exec", "--skip-git-repo-check", "--sandbox", "workspace-write", "--color", "never", "-"],
+                timeoutMs: 45 * 60 * 1000,
+                idleTimeoutMs: 5 * 60 * 1000,
+                firstOutputTimeoutMs: 2 * 60 * 1000,
+                model: {
+                    name: "",
+                    provider: "",
+                    args: [],
+                    env: {}
+                },
+                nativeSession: {
+                    enabled: true,
+                    resumeArgs: ["exec", "resume", "{sessionId}", "--skip-git-repo-check", "-"],
+                    detectSessionId: true,
+                    fallback: "new"
+                },
+                interactive: {
+                    command: "codex",
+                    args: ["resume", "{sessionId}"]
+                }
+            },
+            claude: {
+                command: "claude",
+                args: ["--print", "--permission-mode", "acceptEdits", "--output-format", "text"],
+                timeoutMs: 45 * 60 * 1000,
+                idleTimeoutMs: 5 * 60 * 1000,
+                firstOutputTimeoutMs: 2 * 60 * 1000,
+                model: {
+                    name: "",
+                    provider: "",
+                    args: [],
+                    env: {}
+                },
+                nativeSession: {
+                    enabled: true,
+                    resumeArgs: ["--print", "--resume", "{sessionId}", "--permission-mode", "acceptEdits", "--output-format", "text"],
+                    detectSessionId: true,
+                    fallback: "new"
+                },
+                interactive: {
+                    command: "claude",
+                    args: ["--resume", "{sessionId}"]
+                }
+            },
+            mock: {
+                command: "mock",
+                args: [],
+                model: {
+                    name: "",
+                    provider: "",
+                    args: [],
+                    env: {}
+                },
+                nativeSession: {
+                    enabled: true,
+                    resumeArgs: ["resume", "{sessionId}", "-"],
+                    detectSessionId: true,
+                    fallback: "fail"
+                },
+                interactive: {
+                    command: "mock",
+                    args: ["resume", "{sessionId}"]
+                }
+            }
+        },
+        pairing: {
+            main: "claude",
+            judge: "codex",
+            actor: "codex",
+            critic: "codex"
+        },
+        roles: {
+            main: {
+                title: "Main",
+                instructions: ["Answer the user directly for simple chat and explanation requests."]
+            },
+            judge: {
+                title: "Judge",
+                instructions: ["You clarify requirements and write task files. Do not implement code."]
+            },
+            actor: {
+                title: "Actor",
+                instructions: ["Read Judge files, implement the requested change, and record your work."]
+            },
+            critic: {
+                title: "Critic",
+                instructions: ["Review Actor work against Judge requirements. Lead with blocking findings."]
+            }
+        },
+        ui: {
+            showStatusBar: true,
+            autoOpenFailedWorker: true
+        }
+    };
+}
+export function configPath(projectRoot) {
+    return join(projectRoot, ".parallel-codex", "config.toml");
+}
+export async function loadConfig(projectRoot) {
+    const base = defaultConfig(projectRoot);
+    const file = configPath(projectRoot);
+    if (!(await pathExists(file))) {
+        return base;
+    }
+    const parsed = parse(await readTextIfExists(file));
+    const merged = {
+        ...base,
+        ...parsed,
+        projectRoot,
+        router: {
+            ...base.router,
+            ...(parsed.router ?? {}),
+            codex: {
+                ...base.router.codex,
+                ...(parsed.router?.codex ?? {})
+            }
+        },
+        workers: {
+            codex: {
+                ...base.workers.codex,
+                ...(parsed.workers?.codex ?? {}),
+                model: {
+                    ...base.workers.codex.model,
+                    ...(parsed.workers?.codex?.model ?? {}),
+                    env: {
+                        ...base.workers.codex.model.env,
+                        ...(parsed.workers?.codex?.model?.env ?? {})
+                    }
+                },
+                nativeSession: {
+                    ...base.workers.codex.nativeSession,
+                    ...(parsed.workers?.codex?.nativeSession ?? {})
+                },
+                interactive: {
+                    ...base.workers.codex.interactive,
+                    ...(parsed.workers?.codex?.interactive ?? {})
+                }
+            },
+            claude: {
+                ...base.workers.claude,
+                ...(parsed.workers?.claude ?? {}),
+                model: {
+                    ...base.workers.claude.model,
+                    ...(parsed.workers?.claude?.model ?? {}),
+                    env: {
+                        ...base.workers.claude.model.env,
+                        ...(parsed.workers?.claude?.model?.env ?? {})
+                    }
+                },
+                nativeSession: {
+                    ...base.workers.claude.nativeSession,
+                    ...(parsed.workers?.claude?.nativeSession ?? {})
+                },
+                interactive: {
+                    ...base.workers.claude.interactive,
+                    ...(parsed.workers?.claude?.interactive ?? {})
+                }
+            },
+            mock: {
+                ...base.workers.mock,
+                ...(parsed.workers?.mock ?? {}),
+                model: {
+                    ...base.workers.mock.model,
+                    ...(parsed.workers?.mock?.model ?? {}),
+                    env: {
+                        ...base.workers.mock.model.env,
+                        ...(parsed.workers?.mock?.model?.env ?? {})
+                    }
+                },
+                nativeSession: {
+                    ...base.workers.mock.nativeSession,
+                    ...(parsed.workers?.mock?.nativeSession ?? {})
+                },
+                interactive: {
+                    ...base.workers.mock.interactive,
+                    ...(parsed.workers?.mock?.interactive ?? {})
+                }
+            }
+        },
+        pairing: {
+            ...base.pairing,
+            ...(parsed.pairing ?? {})
+        },
+        roles: {
+            main: {
+                ...base.roles.main,
+                ...(parsed.roles?.main ?? {})
+            },
+            judge: {
+                ...base.roles.judge,
+                ...(parsed.roles?.judge ?? {})
+            },
+            actor: {
+                ...base.roles.actor,
+                ...(parsed.roles?.actor ?? {})
+            },
+            critic: {
+                ...base.roles.critic,
+                ...(parsed.roles?.critic ?? {})
+            }
+        },
+        ui: {
+            ...base.ui,
+            ...(parsed.ui ?? {})
+        }
+    };
+    return AppConfigSchema.parse(merged);
+}
+export async function writeDefaultConfig(projectRoot) {
+    const config = defaultConfig(projectRoot);
+    const tomlText = stringify({
+        router: config.router,
+        workers: config.workers,
+        pairing: config.pairing,
+        roles: config.roles,
+        ui: config.ui
+    });
+    await writeText(configPath(projectRoot), tomlText);
+}

package/dist/core/file-store.js

@@ -0,0 +1,56 @@
+import { mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+export async function ensureDir(path) {
+    await mkdir(path, { recursive: true });
+}
+export async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function writeJson(path, value) {
+    const dir = dirname(path);
+    const tempPath = join(dir, `.${basename(path)}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
+    await ensureDir(dir);
+    await writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    await rename(tempPath, path);
+}
+export async function readJson(path, schema) {
+    const text = await readFile(path, "utf8");
+    return schema.parse(JSON.parse(text));
+}
+export async function appendJsonLine(path, value) {
+    await ensureDir(dirname(path));
+    await writeFile(path, `${JSON.stringify(value)}\n`, { encoding: "utf8", flag: "a" });
+}
+export async function writeText(path, value) {
+    await ensureDir(dirname(path));
+    await writeFile(path, value, "utf8");
+}
+export async function appendText(path, value) {
+    await ensureDir(dirname(path));
+    await writeFile(path, value, { encoding: "utf8", flag: "a" });
+}
+export async function readTextIfExists(path) {
+    if (!(await pathExists(path))) {
+        return "";
+    }
+    return readFile(path, "utf8");
+}
+export async function removeIfExists(path) {
+    try {
+        await unlink(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+}