mini-codex 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JJ Wang
+
+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,231 @@
+# mini-codex
+
+`mini-codex` is a Bun-based coding agent for a single local workspace.
+
+It can:
+- answer workspace questions
+- inspect files and search code
+- make focused file edits
+- run bounded local commands
+- ask short clarification questions when needed
+- keep workspace-local memory
+- use bounded child agents in separate git worktrees
+
+For architecture details, see [doc/ARCHITECTURE.md](/Users/jjwang/repo/mini-codex/doc/ARCHITECTURE.md).
+
+## Who This README Is For
+
+There are two main ways to use this project:
+
+1. Package user
+   Install `mini-codex` and use it against your own workspace or project folder.
+2. Developer
+   Clone this repo, build it, run tests, and change the code.
+
+## Package User
+
+### Requirements
+
+- Bun
+- `git`
+- network access for the remote provider
+- `rg` recommended for the best search experience
+
+Install Bun first if you do not already have it:
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+### Install
+
+Install the package globally with:
+
+```bash
+bun install -g mini-codex
+```
+
+The installed command is:
+
+```bash
+mini-codex
+```
+
+### Login
+
+```bash
+mini-codex auth login
+mini-codex auth status
+```
+
+Tokens are stored at:
+
+```text
+~/.mini-codex/openai-oauth.json
+```
+
+### Happy Path
+
+Run `mini-codex` against a local workspace:
+
+```bash
+mini-codex run "where is auth login implemented" --repo .
+```
+
+Another example:
+
+```bash
+mini-codex run "explain the current repo" --repo .
+```
+
+What to expect:
+- interactive terminal runs show step-by-step progress
+- the agent highlights LLM calls, tool calls, results, clarifications, and final answers
+- each run writes a workspace-local log under `.codex/logs/`
+- workspace memory is stored under `.codex/memory/`
+
+Useful flags:
+- `--json`
+- `--show-llm-details`
+- `--show-tool-results`
+- `--max-steps <n>`
+
+Example:
+
+```bash
+mini-codex run "fix this" --repo . --show-llm-details
+```
+
+### Default Configuration
+
+By default, `mini-codex` uses:
+
+- `MINI_CODEX_PROVIDER=openai-oauth`
+- `MINI_CODEX_MODEL=gpt-5.4`
+
+You usually do not need to set them manually.
+
+## Developer
+
+### Clone And Install
+
+```bash
+git clone https://github.com/wjjnova/mini-codex.git
+cd mini-codex
+bun install
+```
+
+If Bun is not installed yet:
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+### Build
+
+```bash
+bun run build
+```
+
+### Run From Source
+
+```bash
+bun run dev -- run "explain the current repo" --repo .
+```
+
+Auth commands from source:
+
+```bash
+bun run dev -- auth login
+bun run dev -- auth status
+bun run dev -- auth logout
+```
+
+### Link A Local Command
+
+If you want a shell command while developing locally:
+
+```bash
+bun run build
+bun link
+```
+
+Then:
+
+```bash
+mini-codex run "where is auth login implemented" --repo .
+```
+
+### Publish Package
+
+For package publishing steps, see [doc/PUBLISHING.md](/Users/jjwang/repo/mini-codex/doc/PUBLISHING.md).
+
+### Test
+
+Run the full test suite:
+
+```bash
+bun test
+```
+
+Or:
+
+```bash
+bun run test
+```
+
+Run the CLI end-to-end tests:
+
+```bash
+bun run test:e2e
+```
+
+### Develop The Code
+
+Most important source areas:
+
+- CLI: [src/cli.ts](/Users/jjwang/repo/mini-codex/src/cli.ts)
+- Loop: [src/loop.ts](/Users/jjwang/repo/mini-codex/src/loop.ts)
+- Runtime: [src/runtime.ts](/Users/jjwang/repo/mini-codex/src/runtime.ts)
+- Tools: [src/tools.ts](/Users/jjwang/repo/mini-codex/src/tools.ts)
+- Prompting: [src/prompt.ts](/Users/jjwang/repo/mini-codex/src/prompt.ts)
+- Provider: [src/providers/openai.ts](/Users/jjwang/repo/mini-codex/src/providers/openai.ts)
+- Terminal output: [src/terminal.ts](/Users/jjwang/repo/mini-codex/src/terminal.ts)
+
+Repo-local supporting data:
+
+- skills: [.codex/skills](/Users/jjwang/repo/mini-codex/.codex/skills)
+- memory: `.codex/memory/`
+- logs: `.codex/logs/`
+- sub-agents: `.codex/subagents/`
+
+### Cross-Platform Notes
+
+The package-install path is intended to work on macOS, Linux, and Windows with Bun.
+
+Cross-platform behavior in this repo:
+- the installable command prefers built `dist/cli.js`
+- `run_command` uses the platform default shell
+- `rg` is preferred for search
+- `search_files` is the built-in fallback when `rg` is unavailable
+
+## Current Tool Set
+
+- `list_files`
+- `read_file`
+- `search_files`
+- `write_file`
+- `edit_file`
+- `run_command`
+- `write_memory`
+- `spawn_subagents`
+- `wait_subagents`
+- `finish`
+
+## Notes
+
+- This project is intentionally small and local-first.
+- It is not trying to be a full Codex clone.
+- The current provider path is OpenAI OAuth oriented.
+- License: MIT. See [LICENSE](/Users/jjwang/repo/mini-codex/LICENSE).
+- For deeper design detail, use [doc/ARCHITECTURE.md](/Users/jjwang/repo/mini-codex/doc/ARCHITECTURE.md).

package/bin/mini-codex

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+import { existsSync } from "node:fs";
+
+const distEntry = new URL("../dist/cli.js", import.meta.url);
+const sourceEntry = new URL("../src/cli.ts", import.meta.url);
+
+await import(existsSync(distEntry) ? distEntry.href : sourceEntry.href);

package/dist/auth/base.d.ts

@@ -0,0 +1,13 @@
+export interface AuthStatus {
+    provider: string;
+    loggedIn: boolean;
+    expiresAt?: number;
+    expired?: boolean;
+    accountId?: string;
+}
+export interface AuthManager {
+    login(): Promise<void>;
+    logout(): Promise<void>;
+    getStatus(): Promise<AuthStatus>;
+    getAccessToken(): Promise<string>;
+}

package/dist/auth/base.js

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

package/dist/auth/openai-oauth.d.ts

@@ -0,0 +1,7 @@
+import type { AuthManager, AuthStatus } from "./base.js";
+export declare class OpenAIOAuthManager implements AuthManager {
+    login(): Promise<void>;
+    logout(): Promise<void>;
+    getStatus(): Promise<AuthStatus>;
+    getAccessToken(): Promise<string>;
+}

package/dist/auth/openai-oauth.js

@@ -0,0 +1,218 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import http from "node:http";
+import crypto from "node:crypto";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+const AUTHORIZE_URL = "https://auth.openai.com/oauth/authorize";
+const TOKEN_URL = "https://auth.openai.com/oauth/token";
+const REDIRECT_URI = "http://localhost:1455/auth/callback";
+const SCOPE = "openid profile email offline_access";
+const JWT_CLAIM_PATH = "https://api.openai.com/auth";
+const STORE_DIR = path.join(os.homedir(), ".mini-codex");
+const STORE_FILE = path.join(STORE_DIR, "openai-oauth.json");
+function base64url(input) {
+    return input.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function generatePKCE() {
+    const verifier = base64url(crypto.randomBytes(32));
+    const challenge = base64url(crypto.createHash("sha256").update(verifier).digest());
+    return { verifier, challenge };
+}
+function randomState() {
+    return crypto.randomBytes(16).toString("hex");
+}
+function decodeJwt(token) {
+    try {
+        const parts = token.split(".");
+        if (parts.length !== 3)
+            return null;
+        const payload = parts[1];
+        const normalized = payload.replace(/-/g, "+").replace(/_/g, "/");
+        const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
+        return JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function extractAccountId(token) {
+    const payload = decodeJwt(token);
+    return payload?.[JWT_CLAIM_PATH]?.chatgpt_account_id;
+}
+async function ensureStoreDir() {
+    await fs.mkdir(STORE_DIR, { recursive: true });
+}
+async function readStoredToken() {
+    try {
+        const raw = await fs.readFile(STORE_FILE, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function writeStoredToken(token) {
+    await ensureStoreDir();
+    await fs.writeFile(STORE_FILE, JSON.stringify(token, null, 2), "utf8");
+}
+async function exchangeCode(code, verifier) {
+    const response = await fetch(TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            client_id: CLIENT_ID,
+            code,
+            code_verifier: verifier,
+            redirect_uri: REDIRECT_URI,
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`OAuth token exchange failed: HTTP ${response.status} ${await response.text()}`);
+    }
+    const json = await response.json();
+    return {
+        accessToken: json.access_token,
+        refreshToken: json.refresh_token,
+        expiresAt: Date.now() + Number(json.expires_in) * 1000,
+        accountId: extractAccountId(json.access_token),
+    };
+}
+async function refreshToken(refreshToken) {
+    const response = await fetch(TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "refresh_token",
+            client_id: CLIENT_ID,
+            refresh_token: refreshToken,
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`OAuth token refresh failed: HTTP ${response.status} ${await response.text()}`);
+    }
+    const json = await response.json();
+    return {
+        accessToken: json.access_token,
+        refreshToken: json.refresh_token,
+        expiresAt: Date.now() + Number(json.expires_in) * 1000,
+        accountId: extractAccountId(json.access_token),
+    };
+}
+async function openBrowser(url) {
+    try {
+        await execAsync(`open '${url.replace(/'/g, "'\\''")}'`);
+    }
+    catch {
+        console.log(`Open this URL in your browser:\n${url}`);
+    }
+}
+async function waitForAuthorizationCode(state) {
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const server = http.createServer((req, res) => {
+            try {
+                const url = new URL(req.url || "", "http://localhost");
+                if (url.pathname !== "/auth/callback") {
+                    res.statusCode = 404;
+                    res.end("Not found");
+                    return;
+                }
+                if (url.searchParams.get("state") !== state) {
+                    res.statusCode = 400;
+                    res.end("State mismatch");
+                    return;
+                }
+                const code = url.searchParams.get("code");
+                if (!code) {
+                    res.statusCode = 400;
+                    res.end("Missing code");
+                    return;
+                }
+                res.statusCode = 200;
+                res.setHeader("Content-Type", "text/html; charset=utf-8");
+                res.end("<p>Authentication successful. Return to mini-codex.</p>");
+                if (!settled) {
+                    settled = true;
+                    server.close();
+                    resolve(code);
+                }
+            }
+            catch (error) {
+                if (!settled) {
+                    settled = true;
+                    server.close();
+                    reject(error);
+                }
+            }
+        });
+        server.listen(1455, "127.0.0.1", () => undefined);
+        server.on("error", (error) => {
+            if (!settled) {
+                settled = true;
+                reject(error);
+            }
+        });
+        setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                server.close();
+                reject(new Error("OAuth callback timed out after 5 minutes"));
+            }
+        }, 5 * 60 * 1000);
+    });
+}
+export class OpenAIOAuthManager {
+    async login() {
+        const { verifier, challenge } = generatePKCE();
+        const state = randomState();
+        const url = new URL(AUTHORIZE_URL);
+        url.searchParams.set("response_type", "code");
+        url.searchParams.set("client_id", CLIENT_ID);
+        url.searchParams.set("redirect_uri", REDIRECT_URI);
+        url.searchParams.set("scope", SCOPE);
+        url.searchParams.set("code_challenge", challenge);
+        url.searchParams.set("code_challenge_method", "S256");
+        url.searchParams.set("state", state);
+        url.searchParams.set("id_token_add_organizations", "true");
+        url.searchParams.set("codex_cli_simplified_flow", "true");
+        url.searchParams.set("originator", "pi");
+        console.log("Starting OpenAI OAuth login...");
+        await openBrowser(url.toString());
+        const code = await waitForAuthorizationCode(state);
+        const token = await exchangeCode(code, verifier);
+        await writeStoredToken(token);
+        console.log("Login successful.");
+    }
+    async logout() {
+        await fs.rm(STORE_FILE, { force: true });
+    }
+    async getStatus() {
+        const token = await readStoredToken();
+        if (!token) {
+            return { provider: "openai-oauth", loggedIn: false };
+        }
+        const expired = token.expiresAt <= Date.now();
+        return {
+            provider: "openai-oauth",
+            loggedIn: true,
+            expiresAt: token.expiresAt,
+            expired,
+            accountId: token.accountId,
+        };
+    }
+    async getAccessToken() {
+        const token = await readStoredToken();
+        if (!token)
+            throw new Error("Not logged in. Run: bun run dev -- auth login");
+        if (token.expiresAt > Date.now() + 60_000)
+            return token.accessToken;
+        const refreshed = await refreshToken(token.refreshToken);
+        await writeStoredToken(refreshed);
+        return refreshed.accessToken;
+    }
+}

package/dist/cli-args.d.ts

@@ -0,0 +1,10 @@
+export declare function parseArgs(argv: string[]): {
+    command: string;
+    subcommandOrTask: string;
+    repoPath: string;
+    maxSteps: number;
+    json: boolean;
+    depth: number;
+    showLlmDetails: boolean;
+    showToolResults: boolean;
+};

package/dist/cli-args.js

@@ -0,0 +1,20 @@
+import path from "node:path";
+export function parseArgs(argv) {
+    const [command, subcommandOrTask, ...rest] = argv;
+    const repoFlagIndex = rest.indexOf("--repo");
+    const maxStepsIndex = rest.indexOf("--max-steps");
+    const jsonFlag = rest.includes("--json");
+    const depthIndex = rest.indexOf("--depth");
+    const showLlmDetails = rest.includes("--show-llm-details");
+    const showToolResults = rest.includes("--show-tool-results");
+    return {
+        command,
+        subcommandOrTask,
+        repoPath: repoFlagIndex >= 0 && rest[repoFlagIndex + 1] ? path.resolve(rest[repoFlagIndex + 1]) : process.cwd(),
+        maxSteps: maxStepsIndex >= 0 && rest[maxStepsIndex + 1] ? Number(rest[maxStepsIndex + 1]) : 12,
+        json: jsonFlag,
+        depth: depthIndex >= 0 && rest[depthIndex + 1] ? Number(rest[depthIndex + 1]) : 0,
+        showLlmDetails,
+        showToolResults,
+    };
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env bun
+import readline from "node:readline/promises";
+import { renderSession, runLoop } from "./loop.js";
+import { OpenAIOAuthManager } from "./auth/openai-oauth.js";
+import { TerminalRenderer } from "./terminal.js";
+import { parseArgs } from "./cli-args.js";
+async function handleAuth(subcommand) {
+    const auth = new OpenAIOAuthManager();
+    switch (subcommand) {
+        case "login":
+            await auth.login();
+            return;
+        case "status": {
+            const status = await auth.getStatus();
+            console.log(JSON.stringify(status, null, 2));
+            return;
+        }
+        case "logout":
+            await auth.logout();
+            console.log("Logged out.");
+            return;
+        default:
+            console.error("Usage: bun run dev -- auth <login|status|logout>");
+            process.exit(1);
+    }
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.command === "auth") {
+        await handleAuth(args.subcommandOrTask);
+        return;
+    }
+    if (args.command !== "run" || !args.subcommandOrTask) {
+        console.error('Usage: bun run dev -- run "task" --repo <path> [--max-steps 12] [--json] [--depth 0] [--show-llm-details] [--show-tool-results]');
+        console.error('   or: bun run dev -- auth <login|status|logout>');
+        process.exit(1);
+    }
+    const interactive = !args.json && Boolean(process.stdin.isTTY && process.stdout.isTTY) && args.depth === 0;
+    const renderer = interactive ? new TerminalRenderer(true, args.showLlmDetails, args.showToolResults) : null;
+    const askUser = interactive
+        ? async (question) => {
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                const answer = await rl.question("> ");
+                return answer.trim();
+            }
+            finally {
+                rl.close();
+            }
+        }
+        : undefined;
+    const session = await runLoop(args.subcommandOrTask, args.repoPath, {
+        maxSteps: args.maxSteps,
+        depth: args.depth,
+        interactive,
+        renderer,
+        askUser,
+    });
+    if (args.json) {
+        console.log(JSON.stringify(session, null, 2));
+    }
+    else {
+        const lastStep = session.steps.at(-1);
+        const answer = lastStep?.action.type === "tool" && typeof lastStep.action.toolCall.args.answer === "string"
+            ? lastStep.action.toolCall.args.answer
+            : null;
+        if (typeof answer === "string" && answer.trim()) {
+            renderer?.finalAnswer(answer.trim());
+        }
+        if (!interactive) {
+            console.log(renderSession(session, { showToolResults: args.showToolResults }));
+        }
+    }
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/loop.d.ts

@@ -0,0 +1,15 @@
+import type { Session } from "./types.js";
+import type { ModelProvider } from "./providers/base.js";
+import { TerminalRenderer } from "./terminal.js";
+export interface RunLoopOptions {
+    maxSteps?: number;
+    depth?: number;
+    interactive?: boolean;
+    renderer?: TerminalRenderer | null;
+    askUser?: (question: string) => Promise<string>;
+    provider?: ModelProvider;
+}
+export declare function runLoop(task: string, repoPath: string, options?: RunLoopOptions): Promise<Session>;
+export declare function renderSession(session: Session, options?: {
+    showToolResults?: boolean;
+}): string;