codex-sidecar 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nora
+
+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,86 @@
+# codex-sidecar
+
+Claude Code から Codex App Server を薄い CLI 経由で呼び出し、同じ Codex thread を継続利用するための小さな sidecar。
+
+## Install
+
+```bash
+npm install -g codex-sidecar
+npx skills add https://github.com/nora/codex-sidecar --yes --global
+```
+
+前提:
+
+- Node.js 22+
+- `codex` CLI が使えること
+- `codex app-server --listen stdio://` が動くこと
+
+## Why
+
+- Claude Code を主担当にする
+- Codex を senior engineer / reviewer として横に置く
+- broker や Claude Channel を入れず、小さい構成で長いラリーを回せるようにする
+
+## Current Scope
+
+- `codex app-server` を各 CLI 実行時にローカル子プロセスで起動する
+- 1 本の `thread` を state file で保持し、次回以降は resume する
+- CLI から `start / ask / status / reset / stop` を提供する
+- Claude Code 側は Bash または plugin からこの CLI を叩く
+- 既定モデルは `gpt-5.4`、既定 reasoning effort は `high`
+- 現状は state file が `.agents/state/codex-sidecar.json` 固定なので、`1 cwd = 1 sidecar session`
+- thread state は各プロジェクト配下の `.agents/state/codex-sidecar.json` に保存する
+
+`stdio://` は別プロセスから再接続できないため、現実装では常駐 app-server は持たず、各 command が app-server を起動して `threadId` / `threadPath` を再利用する。
+`start` は resume 可能な rollout を materialize するために bootstrap turn を 1 回だけ流す。
+
+## Commands
+
+グローバルインストール後:
+
+```bash
+codex-sidecar start
+codex-sidecar ask "この設計の弱点を挙げて"
+codex-sidecar ask "さっきの2番目の弱点について、最小修正案を具体化して"
+codex-sidecar status
+codex-sidecar reset
+codex-sidecar ask "新しい前提で、この実装方針をレビューして"
+codex-sidecar stop
+```
+
+リポジトリ内での開発:
+
+```bash
+pnpm install
+pnpm qc
+pnpm dev -- help
+pnpm dev -- start
+pnpm dev -- ask "この設計の弱点を挙げて"
+pnpm dev -- status
+pnpm dev -- reset
+pnpm dev -- stop
+```
+
+## Recovery
+
+- `codex-sidecar status` で現在の thread / state を確認する
+- `ask` が resume/state エラーなら `codex-sidecar reset`
+- state file を強制的に消したいなら `codex-sidecar stop`
+
+## Quality
+
+ローカル CI の入口は `pnpm qc`。
+
+- `pnpm lint`
+- `pnpm fmt:check`
+- `pnpm typecheck`
+- `pnpm test`
+- `pnpm build`
+
+Claude Code の `PostToolUse` hook で、`src/*.ts` への編集後に `oxlint --fix` と `oxfmt --write` が自動で走る。
+
+## Docs
+
+- [docs/npm.md](docs/npm.md): npm 初回公開・更新・セキュリティ手順
+- [tasks/progress.md](tasks/progress.md): 軽量ロードマップと進捗チェックリスト
+- [AGENTS.md](AGENTS.md): リポジトリ運用ルール

package/dist/codex/app-server-client.d.ts

@@ -0,0 +1,2 @@
+import type { CodexClient } from "./types.js";
+export declare function createAppServerClient(cwd: string): Promise<CodexClient>;

package/dist/codex/app-server-client.js

@@ -0,0 +1,299 @@
+import { spawn } from "node:child_process";
+import { DEFAULT_MODEL, DEFAULT_REASONING_EFFORT } from "./defaults.js";
+const CLIENT_VERSION = "0.0.0";
+const TURN_TIMEOUT_MS = 5 * 60 * 1000;
+const SIDECAR_BASE_INSTRUCTIONS = [
+    "あなたはこのリポジトリの senior engineer です。",
+    "KISS / DRY / YAGNI を優先してください。",
+    "日本語で返答してください。",
+    "批判的にレビューしてください。",
+    "必要なら代替案を提案してください。",
+    "返答は簡潔にしてください。",
+].join("\n");
+export async function createAppServerClient(cwd) {
+    const client = new AppServerClient(cwd);
+    await client.initialize();
+    return client;
+}
+class AppServerClient {
+    child;
+    pendingRequests = new Map();
+    agentMessages = new Map();
+    completedTurns = new Map();
+    turnWaiters = new Map();
+    stderrLines = [];
+    cwd;
+    nextId = 1;
+    stdoutBuffer = "";
+    closed = false;
+    constructor(cwd) {
+        this.cwd = cwd;
+        this.child = spawn("codex", ["app-server", "--listen", "stdio://"], {
+            cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.child.stdout.setEncoding("utf8");
+        this.child.stdout.on("data", (chunk) => {
+            this.handleStdoutChunk(chunk);
+        });
+        this.child.stderr.setEncoding("utf8");
+        this.child.stderr.on("data", (chunk) => {
+            this.handleStderrChunk(chunk);
+        });
+        this.child.on("exit", (code, signal) => {
+            this.handleExit(code, signal);
+        });
+        this.child.on("error", (error) => {
+            this.handleFatalError(error);
+        });
+    }
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.child.stdin.end();
+        this.child.kill();
+    }
+    async createThread() {
+        const response = await this.request("thread/start", {
+            model: DEFAULT_MODEL,
+            cwd: this.cwd,
+            approvalPolicy: "never",
+            sandbox: "workspace-write",
+            baseInstructions: SIDECAR_BASE_INSTRUCTIONS,
+            personality: "pragmatic",
+            experimentalRawEvents: false,
+            persistExtendedHistory: true,
+        });
+        return response.thread;
+    }
+    async resumeThread(threadId, threadPath) {
+        const response = await this.request("thread/resume", {
+            threadId,
+            path: threadPath ?? undefined,
+            model: DEFAULT_MODEL,
+            cwd: this.cwd,
+            approvalPolicy: "never",
+            sandbox: "workspace-write",
+            baseInstructions: SIDECAR_BASE_INSTRUCTIONS,
+            personality: "pragmatic",
+            persistExtendedHistory: true,
+        });
+        return response.thread;
+    }
+    async archiveThread(threadId) {
+        await this.request("thread/archive", { threadId });
+    }
+    async startTurn(threadId, message) {
+        const response = await this.request("turn/start", {
+            threadId,
+            effort: DEFAULT_REASONING_EFFORT,
+            input: [
+                {
+                    type: "text",
+                    text: message,
+                    text_elements: [],
+                },
+            ],
+        });
+        const turnId = response.turn.id;
+        const completed = this.completedTurns.get(turnId);
+        if (completed) {
+            return this.buildTurnResult(turnId, completed);
+        }
+        return await new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.turnWaiters.delete(turnId);
+                reject(new Error(`Timed out waiting for turn completion: ${turnId}`));
+            }, TURN_TIMEOUT_MS);
+            this.turnWaiters.set(turnId, { resolve, reject, timeout });
+        });
+    }
+    async initialize() {
+        await this.request("initialize", {
+            clientInfo: {
+                name: "codex-sidecar",
+                title: "codex-sidecar",
+                version: CLIENT_VERSION,
+            },
+            capabilities: {
+                experimentalApi: true,
+            },
+        });
+    }
+    handleStdoutChunk(chunk) {
+        this.stdoutBuffer += chunk;
+        let newlineIndex = this.stdoutBuffer.indexOf("\n");
+        while (newlineIndex >= 0) {
+            const line = this.stdoutBuffer.slice(0, newlineIndex).trim();
+            this.stdoutBuffer = this.stdoutBuffer.slice(newlineIndex + 1);
+            if (line) {
+                this.handleMessage(line);
+            }
+            newlineIndex = this.stdoutBuffer.indexOf("\n");
+        }
+    }
+    handleStderrChunk(chunk) {
+        for (const line of chunk.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed) {
+                continue;
+            }
+            this.stderrLines.push(trimmed);
+            if (this.stderrLines.length > 20) {
+                this.stderrLines.shift();
+            }
+        }
+    }
+    handleMessage(line) {
+        const message = JSON.parse(line);
+        if (typeof message.method === "string") {
+            this.handleNotification(message.method, message.params);
+            return;
+        }
+        if (typeof message.id !== "number") {
+            return;
+        }
+        const handler = this.pendingRequests.get(message.id);
+        if (!handler) {
+            return;
+        }
+        this.pendingRequests.delete(message.id);
+        if (isJsonRpcFailure(message)) {
+            handler.reject(new Error(message.error.message));
+            return;
+        }
+        if ("result" in message) {
+            handler.resolve(message.result);
+            return;
+        }
+        handler.reject(new Error("Received malformed JSON-RPC response"));
+    }
+    handleNotification(method, params) {
+        if (!isRecord(params)) {
+            return;
+        }
+        if (method === "item/completed") {
+            this.handleItemCompleted(params);
+            return;
+        }
+        if (method === "turn/completed") {
+            this.handleTurnCompleted(params);
+        }
+    }
+    handleItemCompleted(params) {
+        const { turnId, item } = params;
+        if (typeof turnId !== "string" || !isRecord(item)) {
+            return;
+        }
+        if (item.type !== "agentMessage" || typeof item.text !== "string") {
+            return;
+        }
+        const messages = this.agentMessages.get(turnId) ?? [];
+        messages.push(item.text);
+        this.agentMessages.set(turnId, messages);
+    }
+    handleTurnCompleted(params) {
+        const { turn } = params;
+        if (!isRecord(turn) || typeof turn.id !== "string") {
+            return;
+        }
+        const status = normalizeTurnStatus(turn.status);
+        if (!status) {
+            return;
+        }
+        const errorMessage = isRecord(turn.error) && typeof turn.error.message === "string" ? turn.error.message : null;
+        const completedTurn = { status, errorMessage };
+        this.completedTurns.set(turn.id, completedTurn);
+        const waiter = this.turnWaiters.get(turn.id);
+        if (!waiter) {
+            return;
+        }
+        clearTimeout(waiter.timeout);
+        this.turnWaiters.delete(turn.id);
+        waiter.resolve(this.buildTurnResult(turn.id, completedTurn));
+    }
+    buildTurnResult(turnId, completedTurn) {
+        const message = (this.agentMessages.get(turnId) ?? []).join("\n\n").trim();
+        return {
+            turnId,
+            status: completedTurn.status,
+            message,
+            errorMessage: completedTurn.errorMessage,
+        };
+    }
+    handleExit(code, signal) {
+        if (this.closed) {
+            return;
+        }
+        const reason = new Error(`codex app-server exited unexpectedly (${formatExit(code, signal)})${this.formatStderrSuffix()}`);
+        this.closed = true;
+        this.rejectAll(reason);
+    }
+    handleFatalError(error) {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.rejectAll(error);
+    }
+    rejectAll(error) {
+        for (const handler of this.pendingRequests.values()) {
+            handler.reject(error);
+        }
+        this.pendingRequests.clear();
+        for (const waiter of this.turnWaiters.values()) {
+            clearTimeout(waiter.timeout);
+            waiter.reject(error);
+        }
+        this.turnWaiters.clear();
+    }
+    formatStderrSuffix() {
+        if (this.stderrLines.length === 0) {
+            return "";
+        }
+        return `: ${this.stderrLines.at(-1)}`;
+    }
+    async request(method, params) {
+        if (this.closed) {
+            throw new Error("codex app-server client is already closed");
+        }
+        const id = this.nextId++;
+        const payload = JSON.stringify({
+            jsonrpc: "2.0",
+            id,
+            method,
+            params,
+        });
+        const responsePromise = new Promise((resolve, reject) => {
+            this.pendingRequests.set(id, {
+                resolve: (value) => resolve(value),
+                reject,
+            });
+        });
+        this.child.stdin.write(`${payload}\n`);
+        return await responsePromise;
+    }
+}
+function normalizeTurnStatus(status) {
+    if (status === "completed" || status === "failed" || status === "interrupted") {
+        return status;
+    }
+    return null;
+}
+function formatExit(code, signal) {
+    if (signal) {
+        return `signal ${signal}`;
+    }
+    return `code ${code ?? "unknown"}`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isJsonRpcFailure(value) {
+    return (typeof value.id === "number" &&
+        isRecord(value.error) &&
+        typeof value.error.code === "number" &&
+        typeof value.error.message === "string");
+}

package/dist/codex/defaults.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_MODEL = "gpt-5.4";
+export declare const DEFAULT_REASONING_EFFORT = "high";

package/dist/codex/defaults.js

@@ -0,0 +1,2 @@
+export const DEFAULT_MODEL = "gpt-5.4";
+export const DEFAULT_REASONING_EFFORT = "high";

package/dist/codex/session.d.ts

@@ -0,0 +1 @@
+export declare const SESSION_BOOTSTRAP_MESSAGE = "sidecar \u30BB\u30C3\u30B7\u30E7\u30F3\u3092\u958B\u59CB\u3057\u307E\u3059\u3002\u4EE5\u5F8C\u306E\u76F8\u8AC7\u306B\u5099\u3048\u3066\u304F\u3060\u3055\u3044\u3002\u3053\u306E turn \u3067\u306F\u300C\u4E86\u89E3\u3057\u307E\u3057\u305F\u3002\u300D\u3068\u3060\u3051\u8FD4\u7B54\u3057\u3066\u304F\u3060\u3055\u3044\u3002";

package/dist/codex/session.js

@@ -0,0 +1 @@
+export const SESSION_BOOTSTRAP_MESSAGE = "sidecar セッションを開始します。以後の相談に備えてください。この turn では「了解しました。」とだけ返答してください。";

package/dist/codex/state.d.ts

@@ -0,0 +1,10 @@
+import type { SidecarState } from "./types.js";
+export declare class InvalidStateFileError extends Error {
+    readonly stateFilePath: string;
+    constructor(stateFilePath: string, message: string);
+}
+export declare function isInvalidStateFileError(error: unknown): error is InvalidStateFileError;
+export declare function getDefaultStateFilePath(cwd: string): string;
+export declare function readState(stateFilePath: string): Promise<SidecarState | null>;
+export declare function writeState(stateFilePath: string, state: SidecarState): Promise<void>;
+export declare function deleteState(stateFilePath: string): Promise<void>;

package/dist/codex/state.js

@@ -0,0 +1,68 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+export class InvalidStateFileError extends Error {
+    stateFilePath;
+    constructor(stateFilePath, message) {
+        super(`Invalid sidecar state file: ${stateFilePath}: ${message}`);
+        this.stateFilePath = stateFilePath;
+        this.name = "InvalidStateFileError";
+    }
+}
+export function isInvalidStateFileError(error) {
+    return error instanceof InvalidStateFileError;
+}
+export function getDefaultStateFilePath(cwd) {
+    return path.join(cwd, ".agents", "state", "codex-sidecar.json");
+}
+export async function readState(stateFilePath) {
+    try {
+        const raw = await readFile(stateFilePath, "utf8");
+        return validateState(stateFilePath, JSON.parse(raw));
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return null;
+        }
+        if (error instanceof SyntaxError) {
+            throw new InvalidStateFileError(stateFilePath, "invalid JSON");
+        }
+        throw error;
+    }
+}
+export async function writeState(stateFilePath, state) {
+    await mkdir(path.dirname(stateFilePath), { recursive: true });
+    await writeFile(stateFilePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+export async function deleteState(stateFilePath) {
+    await rm(stateFilePath, { force: true });
+}
+function validateState(stateFilePath, value) {
+    if (!isRecord(value)) {
+        throw new InvalidStateFileError(stateFilePath, "expected object");
+    }
+    const { version, threadId, threadPath, cwd, startedAt, updatedAt } = value;
+    if (version !== 1) {
+        throw new InvalidStateFileError(stateFilePath, "unsupported version");
+    }
+    if (typeof threadId !== "string" ||
+        (threadPath !== null && typeof threadPath !== "string") ||
+        typeof cwd !== "string" ||
+        typeof startedAt !== "string" ||
+        typeof updatedAt !== "string") {
+        throw new InvalidStateFileError(stateFilePath, "missing required fields");
+    }
+    return {
+        version,
+        threadId,
+        threadPath,
+        cwd,
+        startedAt,
+        updatedAt,
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isMissingFileError(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

package/dist/codex/types.d.ts

@@ -0,0 +1,34 @@
+export interface SidecarState {
+    version: 1;
+    threadId: string;
+    threadPath: string | null;
+    cwd: string;
+    startedAt: string;
+    updatedAt: string;
+}
+export interface CodexThread {
+    id: string;
+    path: string | null;
+    cwd: string;
+}
+export interface CodexTurnResult {
+    turnId: string;
+    status: "completed" | "failed" | "interrupted";
+    message: string;
+    errorMessage: string | null;
+}
+export interface CodexClient {
+    createThread(): Promise<CodexThread>;
+    resumeThread(threadId: string, threadPath?: string | null): Promise<CodexThread>;
+    archiveThread(threadId: string): Promise<void>;
+    startTurn(threadId: string, message: string): Promise<CodexTurnResult>;
+    close(): Promise<void>;
+}
+export interface CommandContext {
+    cwd: string;
+    now: () => Date;
+    stateFilePath: string;
+    stdout: (message: string) => void;
+    stderr: (message: string) => void;
+    createClient: (cwd: string) => Promise<CodexClient>;
+}

package/dist/codex/types.js

@@ -0,0 +1 @@
+export {};

package/dist/commands/ask.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../codex/types.js";
+export declare function runAskCommand(context: CommandContext, message: string): Promise<void>;

package/dist/commands/ask.js

@@ -0,0 +1,37 @@
+import { formatResumeFailureMessage, readStateWithRecoveryHint } from "./errors.js";
+import { writeState } from "../codex/state.js";
+export async function runAskCommand(context, message) {
+    if (!message.trim()) {
+        throw new Error("Usage: codex-sidecar ask <message>");
+    }
+    const state = await readStateWithRecoveryHint(context.stateFilePath);
+    if (!state) {
+        throw new Error("Sidecar session is not started. Run `codex-sidecar start`.");
+    }
+    const client = await context.createClient(context.cwd);
+    try {
+        const thread = await resumeThreadWithRecoveryHint(client, state.threadId, state.threadPath);
+        const turn = await client.startTurn(thread.id, message);
+        await writeState(context.stateFilePath, {
+            ...state,
+            threadPath: thread.path,
+            cwd: thread.cwd,
+            updatedAt: context.now().toISOString(),
+        });
+        if (turn.status !== "completed") {
+            throw new Error(turn.errorMessage ?? `Turn ended with status: ${turn.status}`);
+        }
+        context.stdout(turn.message);
+    }
+    finally {
+        await client.close();
+    }
+}
+async function resumeThreadWithRecoveryHint(client, threadId, threadPath) {
+    try {
+        return await client.resumeThread(threadId, threadPath);
+    }
+    catch (error) {
+        throw new Error(formatResumeFailureMessage(threadId, threadPath, error));
+    }
+}

package/dist/commands/errors.d.ts

@@ -0,0 +1,7 @@
+import { InvalidStateFileError, isInvalidStateFileError } from "../codex/state.js";
+import type { SidecarState } from "../codex/types.js";
+export declare function readStateWithRecoveryHint(stateFilePath: string): Promise<SidecarState | null>;
+export declare function formatStateRecoveryMessage(error: InvalidStateFileError): string;
+export declare function formatResumeFailureMessage(threadId: string, threadPath: string | null, error: unknown): string;
+export declare function formatArchiveWarning(threadId: string, error: unknown): string;
+export { isInvalidStateFileError };

package/dist/commands/errors.js

@@ -0,0 +1,32 @@
+import { isInvalidStateFileError, readState } from "../codex/state.js";
+export async function readStateWithRecoveryHint(stateFilePath) {
+    try {
+        return await readState(stateFilePath);
+    }
+    catch (error) {
+        if (isInvalidStateFileError(error)) {
+            throw new Error(formatStateRecoveryMessage(error));
+        }
+        throw error;
+    }
+}
+export function formatStateRecoveryMessage(error) {
+    return [
+        error.message,
+        "Run `codex-sidecar reset` to recreate the sidecar thread, or `codex-sidecar stop` to clear local state.",
+    ].join("\n");
+}
+export function formatResumeFailureMessage(threadId, threadPath, error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return [
+        `Failed to resume sidecar thread: ${threadId}`,
+        `Thread path: ${threadPath ?? "(none)"}`,
+        `Reason: ${reason}`,
+        "Run `codex-sidecar reset` to recreate the sidecar thread, or `codex-sidecar stop` to clear local state.",
+    ].join("\n");
+}
+export function formatArchiveWarning(threadId, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return `Archive warning for ${threadId}: ${message}`;
+}
+export { isInvalidStateFileError };

package/dist/commands/reset.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../codex/types.js";
+export declare function runResetCommand(context: CommandContext): Promise<void>;

package/dist/commands/reset.js

@@ -0,0 +1,54 @@
+import { formatArchiveWarning, formatStateRecoveryMessage } from "./errors.js";
+import { SESSION_BOOTSTRAP_MESSAGE } from "../codex/session.js";
+import { isInvalidStateFileError, readState, writeState } from "../codex/state.js";
+export async function runResetCommand(context) {
+    const existingState = await readExistingState(context);
+    if (existingState.kind === "missing") {
+        throw new Error("Sidecar session is not started. Run `codex-sidecar start`.");
+    }
+    const client = await context.createClient(context.cwd);
+    try {
+        if (existingState.kind === "active") {
+            try {
+                await client.archiveThread(existingState.threadId);
+            }
+            catch (error) {
+                context.stderr(formatArchiveWarning(existingState.threadId, error));
+            }
+        }
+        const thread = await client.createThread();
+        const turn = await client.startTurn(thread.id, SESSION_BOOTSTRAP_MESSAGE);
+        if (turn.status !== "completed") {
+            throw new Error(turn.errorMessage ?? `Turn ended with status: ${turn.status}`);
+        }
+        const timestamp = context.now().toISOString();
+        await writeState(context.stateFilePath, {
+            version: 1,
+            threadId: thread.id,
+            threadPath: thread.path,
+            cwd: thread.cwd,
+            startedAt: timestamp,
+            updatedAt: timestamp,
+        });
+        context.stdout(`Reset sidecar thread: ${thread.id}`);
+    }
+    finally {
+        await client.close();
+    }
+}
+async function readExistingState(context) {
+    try {
+        const state = await readState(context.stateFilePath);
+        if (!state) {
+            return { kind: "missing" };
+        }
+        return { kind: "active", threadId: state.threadId };
+    }
+    catch (error) {
+        if (!isInvalidStateFileError(error)) {
+            throw error;
+        }
+        context.stderr(formatStateRecoveryMessage(error));
+        return { kind: "invalid" };
+    }
+}

package/dist/commands/start.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../codex/types.js";
+export declare function runStartCommand(context: CommandContext): Promise<void>;

package/dist/commands/start.js

@@ -0,0 +1,29 @@
+import { SESSION_BOOTSTRAP_MESSAGE } from "../codex/session.js";
+import { readState, writeState } from "../codex/state.js";
+export async function runStartCommand(context) {
+    const existingState = await readState(context.stateFilePath);
+    if (existingState) {
+        throw new Error(`Sidecar session is already active: ${existingState.threadId}`);
+    }
+    const client = await context.createClient(context.cwd);
+    try {
+        const thread = await client.createThread();
+        const turn = await client.startTurn(thread.id, SESSION_BOOTSTRAP_MESSAGE);
+        if (turn.status !== "completed") {
+            throw new Error(turn.errorMessage ?? `Turn ended with status: ${turn.status}`);
+        }
+        const timestamp = context.now().toISOString();
+        await writeState(context.stateFilePath, {
+            version: 1,
+            threadId: thread.id,
+            threadPath: thread.path,
+            cwd: thread.cwd,
+            startedAt: timestamp,
+            updatedAt: timestamp,
+        });
+        context.stdout(`Started sidecar thread: ${thread.id}`);
+    }
+    finally {
+        await client.close();
+    }
+}

package/dist/commands/status.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../codex/types.js";
+export declare function runStatusCommand(context: CommandContext): Promise<void>;

package/dist/commands/status.js

@@ -0,0 +1,43 @@
+import { DEFAULT_MODEL, DEFAULT_REASONING_EFFORT } from "../codex/defaults.js";
+import { formatStateRecoveryMessage, isInvalidStateFileError } from "./errors.js";
+import { readState } from "../codex/state.js";
+export async function runStatusCommand(context) {
+    try {
+        const state = await readState(context.stateFilePath);
+        if (!state) {
+            context.stdout(formatStoppedStatus(context.stateFilePath));
+            return;
+        }
+        context.stdout([
+            "Sidecar session: active",
+            `Thread ID: ${state.threadId}`,
+            `Thread path: ${state.threadPath ?? "(none)"}`,
+            `Thread cwd: ${state.cwd}`,
+            `Started at: ${state.startedAt}`,
+            `Updated at: ${state.updatedAt}`,
+            `State file: ${context.stateFilePath}`,
+            `Default model: ${DEFAULT_MODEL}`,
+            `Default reasoning effort: ${DEFAULT_REASONING_EFFORT}`,
+        ].join("\n"));
+    }
+    catch (error) {
+        if (!isInvalidStateFileError(error)) {
+            throw error;
+        }
+        context.stdout([
+            "Sidecar session: invalid-state",
+            `State file: ${context.stateFilePath}`,
+            formatStateRecoveryMessage(error),
+            `Default model: ${DEFAULT_MODEL}`,
+            `Default reasoning effort: ${DEFAULT_REASONING_EFFORT}`,
+        ].join("\n"));
+    }
+}
+function formatStoppedStatus(stateFilePath) {
+    return [
+        "Sidecar session: stopped",
+        `State file: ${stateFilePath}`,
+        `Default model: ${DEFAULT_MODEL}`,
+        `Default reasoning effort: ${DEFAULT_REASONING_EFFORT}`,
+    ].join("\n");
+}

package/dist/commands/stop.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "../codex/types.js";
+export declare function runStopCommand(context: CommandContext): Promise<void>;

package/dist/commands/stop.js

@@ -0,0 +1,41 @@
+import { formatArchiveWarning, formatStateRecoveryMessage } from "./errors.js";
+import { deleteState, isInvalidStateFileError, readState } from "../codex/state.js";
+export async function runStopCommand(context) {
+    const state = await readStateForStop(context);
+    if (state.kind === "missing") {
+        context.stdout("No active sidecar session.");
+        return;
+    }
+    if (state.kind === "active") {
+        const client = await context.createClient(context.cwd);
+        try {
+            try {
+                await client.archiveThread(state.threadId);
+            }
+            catch (error) {
+                context.stderr(formatArchiveWarning(state.threadId, error));
+            }
+        }
+        finally {
+            await client.close();
+        }
+    }
+    await deleteState(context.stateFilePath);
+    context.stdout("Stopped sidecar session.");
+}
+async function readStateForStop(context) {
+    try {
+        const state = await readState(context.stateFilePath);
+        if (!state) {
+            return { kind: "missing" };
+        }
+        return { kind: "active", threadId: state.threadId };
+    }
+    catch (error) {
+        if (!isInvalidStateFileError(error)) {
+            throw error;
+        }
+        context.stderr(formatStateRecoveryMessage(error));
+        return { kind: "invalid" };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCli } from "./main.js";
+void runCli(process.argv.slice(2));

package/dist/main.d.ts

@@ -0,0 +1,7 @@
+import type { CommandContext } from "./codex/types.js";
+export declare function getUsageText(): string;
+interface RunCliOptions {
+    context?: Partial<CommandContext>;
+}
+export declare function runCli(argv: readonly string[], options?: RunCliOptions): Promise<void>;
+export {};

package/dist/main.js

@@ -0,0 +1,61 @@
+import { runAskCommand } from "./commands/ask.js";
+import { runResetCommand } from "./commands/reset.js";
+import { runStartCommand } from "./commands/start.js";
+import { runStatusCommand } from "./commands/status.js";
+import { runStopCommand } from "./commands/stop.js";
+import { createAppServerClient } from "./codex/app-server-client.js";
+import { getDefaultStateFilePath } from "./codex/state.js";
+export function getUsageText() {
+    return `Usage: codex-sidecar <command> [args]
+
+Commands:
+  start           Create and save a new Codex sidecar thread
+  ask <message>   Send a message to the active Codex thread
+  status          Show current sidecar state and default model settings
+  reset           Archive the current thread and create a new one
+  stop            Archive the current thread and clear local state`;
+}
+export async function runCli(argv, options = {}) {
+    const context = createCommandContext(options.context);
+    const normalizedArgv = argv[0] === "--" ? argv.slice(1) : argv;
+    const [command = "help", ...rest] = normalizedArgv;
+    try {
+        switch (command) {
+            case "start":
+                await runStartCommand(context);
+                return;
+            case "ask":
+                await runAskCommand(context, rest.join(" "));
+                return;
+            case "reset":
+                await runResetCommand(context);
+                return;
+            case "status":
+                await runStatusCommand(context);
+                return;
+            case "stop":
+                await runStopCommand(context);
+                return;
+            default:
+                context.stdout(getUsageText());
+        }
+    }
+    catch (error) {
+        context.stderr(getErrorMessage(error));
+        process.exitCode = 1;
+    }
+}
+function createCommandContext(overrides) {
+    const cwd = overrides?.cwd ?? process.cwd();
+    return {
+        cwd,
+        now: overrides?.now ?? (() => new Date()),
+        stateFilePath: overrides?.stateFilePath ?? getDefaultStateFilePath(cwd),
+        stdout: overrides?.stdout ?? console.log,
+        stderr: overrides?.stderr ?? console.error,
+        createClient: overrides?.createClient ?? createAppServerClient,
+    };
+}
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "codex-sidecar",
+  "version": "0.1.0",
+  "description": "Persistent Codex App Server sidecar CLI for Claude Code.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nora/codex-sidecar.git"
+  },
+  "homepage": "https://github.com/nora/codex-sidecar#readme",
+  "bugs": {
+    "url": "https://github.com/nora/codex-sidecar/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@10.29.3",
+  "files": [
+    "dist",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "codex-sidecar": "dist/index.js"
+  },
+  "scripts": {
+    "prepack": "pnpm build",
+    "lint": "pnpm oxlint src",
+    "lint:fix": "pnpm oxlint --fix src",
+    "fmt": "pnpm oxfmt --write src",
+    "fmt:check": "pnpm oxfmt --check src",
+    "build": "tsc -p tsconfig.json",
+    "test": "pnpm vitest run",
+    "test:cov": "pnpm vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "qc": "scripts/quality-check.sh",
+    "dev": "tsx src/index.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^4.1.2",
+    "oxfmt": "^0.42.0",
+    "oxlint": "^1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.2"
+  }
+}