@9thprotocol/cli 0.1.0

package/LICENSE

@@ -0,0 +1,16 @@
+9th Protocol — Proprietary License
+
+Copyright (c) 2026 9th Protocol. All rights reserved.
+
+This software and its source code are the property of 9th Protocol.
+It is licensed, not sold. You may install and use the unmodified
+package for its intended purpose. You may not copy, modify, merge,
+publish, distribute, sublicense, decompile, or reverse engineer it,
+or use it to build a competing agent product, without a separate
+written license from 9th Protocol.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED. IN NO EVENT SHALL 9TH PROTOCOL BE LIABLE FOR
+ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM THE SOFTWARE.
+
+Contact: licensing@9thprotocol.com

package/README.md

@@ -0,0 +1,43 @@
+# 9p — the 9th Protocol terminal coding agent
+
+An agentic coder for your terminal, powered by OpenRouter so you can use the
+model of your choice: the agent loop, tools, permissions, sub-agents, memory
+and model routing all live in `9p`. Subscriptions and credit budgets are
+managed on the [9th Protocol dashboard](https://9thprotocol.com).
+
+## Install
+
+```sh
+npm install -g @9thprotocol/cli
+```
+
+Requires Node 22 or newer (macOS and Linux; Windows best-effort).
+
+## Quick start
+
+```sh
+9p login     # opens a browser to sign in / create your account
+9p           # start an interactive session in your project directory
+```
+
+Other modes:
+
+```sh
+9p --plain            # non-TUI REPL for scripting and CI
+9p serve 4310         # local web session UI on port 4310
+9p init               # set up a project config / vault
+9p map                # generate a codebase wiki
+```
+
+Credentials are stored in `~/.9p/auth.json`. To use your own OpenRouter key
+instead of the platform, set `OPENROUTER_API_KEY`.
+
+## Links
+
+- Dashboard: https://9thprotocol.com
+- Docs: https://docs.9thprotocol.com
+
+## License
+
+Proprietary — see [LICENSE](./LICENSE). The engine it runs on is
+[`@9thprotocol/agent-core`](https://www.npmjs.com/package/@9thprotocol/agent-core).

package/dist/init.d.ts

@@ -0,0 +1,2 @@
+/** `9p init`: set up project memory: plain 9P.md, or an Obsidian-style vault. */
+export declare function runInit(cwd: string): Promise<void>;

package/dist/init.js

@@ -0,0 +1,61 @@
+import readline from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import fs from "node:fs";
+import path from "node:path";
+import { saveProjectConfig, scaffoldVault, loadProjectConfig } from "@9thprotocol/agent-core";
+import { cyan, dim, yellow } from "./shared.js";
+const STARTER_9P_MD = `# Project memory
+
+Standing instructions for the 9p agent in this project. Keep this file short -
+it loads into every session.
+
+## Conventions
+- (add your project's conventions here)
+`;
+/** `9p init`: set up project memory: plain 9P.md, or an Obsidian-style vault. */
+export async function runInit(cwd) {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    // piped/scripted stdin can hit EOF mid-question. Treat it as "accept defaults"
+    let closed = false;
+    const onClose = new Promise((resolve) => rl.once("close", () => {
+        closed = true;
+        resolve("");
+    }));
+    const ask = (q) => (closed ? Promise.resolve("") : Promise.race([rl.question(q), onClose]));
+    console.log(cyan("9p init, project memory setup"));
+    const existing = loadProjectConfig(cwd);
+    if (existing.vault) {
+        console.log(dim(`vault already configured: ${existing.vault}`));
+    }
+    const choice = (await ask(`How should this project remember things?\n` +
+        `  1. simple, a 9P.md file with standing instructions\n` +
+        `  2. vault, an Obsidian-style folder: index, jobs, daily logs, decisions, codebase maps\n` +
+        `choose [1/2]: `)).trim();
+    if (choice === "2") {
+        const answer = (await ask(`vault location (default: ./vault): `)).trim();
+        const vaultRel = answer || "vault";
+        const vaultAbs = path.resolve(cwd, vaultRel);
+        const created = scaffoldVault(vaultAbs);
+        saveProjectConfig(cwd, { ...existing, vault: vaultRel });
+        console.log(created.length ? dim(`created:\n  ${created.join("\n  ")}`) : dim("vault already scaffolded"));
+        console.log(`${cyan("vault linked.")} The agent now reads ${vaultRel}/INDEX.md first, appends instead of
+creating notes, and logs work to daily notes. Run ${cyan("9p map")} to generate codebase maps.`);
+        console.log(dim("Tip: open the vault folder in Obsidian (obsidian.md) to see the knowledge graph.\n" +
+            "Your memory store stays on this device; prompts that reference it go to the models you use."));
+    }
+    else {
+        const file = path.join(cwd, "9P.md");
+        if (fs.existsSync(file)) {
+            console.log(dim(`9P.md already exists at ${file}, left untouched`));
+        }
+        else {
+            fs.writeFileSync(file, STARTER_9P_MD);
+            console.log(`${cyan("created")} ${file}. It loads into every session in this project.`);
+        }
+        if (choice !== "1" && choice !== "")
+            console.log(yellow("(unrecognized choice, defaulted to simple)"));
+    }
+    if (!closed)
+        rl.close();
+}
+//# sourceMappingURL=init.js.map

package/dist/login.d.ts

@@ -0,0 +1,4 @@
+export declare function runLogin(): Promise<void>;
+export declare function runLogout(): Promise<void>;
+/** Prompt-based fallback for `9p login --paste` (headless boxes with no browser). */
+export declare function runLoginPaste(): Promise<void>;

package/dist/login.js

@@ -0,0 +1,161 @@
+/**
+ * `9p login` / `9p logout`: device authorization grant (RFC 8628).
+ *
+ * Replaces hand-editing ~/.9p/auth.json. The CLI never sees the password: it
+ * gets a short code, the user approves it in the browser, and the CLI polls
+ * until tokens come back.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import readline from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { cyan, dim, red, yellow } from "./shared.js";
+const DEFAULT_API_URL = "https://9th-prot-api.bundleboss.net/v1";
+const authFile = path.join(os.homedir(), ".9p", "auth.json");
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Best-effort browser open; the code is always printed so this failing is harmless. */
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+        spawn(cmd, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" })
+            .on("error", () => { })
+            .unref();
+    }
+    catch {
+        // no browser available. The printed URL is the fallback
+    }
+}
+function readAuthFile() {
+    try {
+        return JSON.parse(fs.readFileSync(authFile, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeAuthFile(data) {
+    fs.mkdirSync(path.dirname(authFile), { recursive: true });
+    // 0600: this file holds a refresh token good for 30 days.
+    fs.writeFileSync(authFile, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+    fs.chmodSync(authFile, 0o600);
+}
+export async function runLogin() {
+    const apiUrl = (process.env.NINEP_API_URL ?? DEFAULT_API_URL).replace(/\/$/, "");
+    let start;
+    try {
+        const res = await fetch(`${apiUrl}/auth/device/code`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ clientLabel: `9p CLI on ${os.hostname()} (${process.platform})` }),
+        });
+        if (!res.ok)
+            throw new Error(`${res.status}: ${await res.text()}`);
+        start = (await res.json());
+    }
+    catch (err) {
+        console.error(red("Could not reach the 9th Protocol API.") + ` ${String(err)}`);
+        console.error(dim(`API URL: ${apiUrl}, override with NINEP_API_URL`));
+        process.exit(1);
+    }
+    console.log(`\n${cyan("Sign in to 9th Protocol")}`);
+    console.log(`\n  code:  ${cyan(start.userCode)}`);
+    console.log(`  open:  ${start.verificationUri}\n`);
+    console.log(dim("Approve the code in your browser. Waiting…"));
+    openBrowser(start.verificationUriComplete);
+    const deadline = Date.now() + start.expiresIn * 1000;
+    let interval = Math.max(1, start.interval) * 1000;
+    while (Date.now() < deadline) {
+        await sleep(interval);
+        let payload;
+        let ok;
+        try {
+            const res = await fetch(`${apiUrl}/auth/device/token`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ deviceCode: start.deviceCode }),
+            });
+            ok = res.ok;
+            payload = (await res.json());
+        }
+        catch {
+            continue; // transient network blip. Keep polling until the deadline
+        }
+        if (ok) {
+            const tokens = payload;
+            writeAuthFile({
+                ...readAuthFile(),
+                apiUrl,
+                token: tokens.accessToken,
+                refreshToken: tokens.refreshToken,
+                email: tokens.user.email,
+            });
+            console.log(`\n${cyan("✓ signed in")} as ${tokens.user.email} ${dim(`(plan: ${tokens.user.plan})`)}`);
+            console.log(dim(`credentials saved to ${authFile}`));
+            return;
+        }
+        switch (payload.error) {
+            case "authorization_pending":
+                break; // expected while the user is still approving
+            case "slow_down":
+                interval += 2000; // the server says we're too eager
+                break;
+            case "access_denied":
+                console.error(`\n${red("Request denied.")} Nothing was saved.`);
+                process.exit(1);
+            // eslint-disable-next-line no-fallthrough
+            case "expired_token":
+                console.error(`\n${red("Code expired.")} Run ${cyan("9p login")} again.`);
+                process.exit(1);
+            // eslint-disable-next-line no-fallthrough
+            default:
+                console.error(`\n${red("Login failed:")} ${String(payload.message ?? payload.error)}`);
+                process.exit(1);
+        }
+    }
+    console.error(`\n${red("Timed out")} waiting for approval. Run ${cyan("9p login")} again.`);
+    process.exit(1);
+}
+export async function runLogout() {
+    const file = readAuthFile();
+    if (!file.token && !file.refreshToken) {
+        console.log(dim("Not signed in."));
+        return;
+    }
+    const apiUrl = String(file.apiUrl ?? process.env.NINEP_API_URL ?? DEFAULT_API_URL).replace(/\/$/, "");
+    if (typeof file.refreshToken === "string") {
+        // Revoke server-side so a leaked file can't be replayed.
+        try {
+            await fetch(`${apiUrl}/auth/logout`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ refreshToken: file.refreshToken }),
+            });
+        }
+        catch {
+            console.log(yellow("Could not reach the API to revoke the token; clearing locally."));
+        }
+    }
+    // Keep any BYOK key, logging out of the platform shouldn't wipe that.
+    const { token: _t, refreshToken: _r, apiUrl: _u, email: _e, ...rest } = file;
+    if (Object.keys(rest).length)
+        writeAuthFile(rest);
+    else
+        fs.rmSync(authFile, { force: true });
+    console.log(cyan("✓ signed out"));
+}
+/** Prompt-based fallback for `9p login --paste` (headless boxes with no browser). */
+export async function runLoginPaste() {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    const apiUrl = ((await rl.question(`API URL [${DEFAULT_API_URL}]: `)).trim() || DEFAULT_API_URL).replace(/\/$/, "");
+    const token = (await rl.question("access token: ")).trim();
+    rl.close();
+    if (!token) {
+        console.error(red("No token given."));
+        process.exit(1);
+    }
+    writeAuthFile({ ...readAuthFile(), apiUrl, token });
+    console.log(cyan("✓ saved") + dim(` → ${authFile}`));
+}
+//# sourceMappingURL=login.js.map

package/dist/main.d.ts

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

package/dist/main.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * 9p, the 9th Protocol coding agent.
+ *   9p                interactive session (Ink TUI in a TTY; --plain for the bare REPL)
+ *   9p login          sign in via the browser (device grant); --paste for headless
+ *   9p logout         revoke and clear saved credentials
+ *   9p init           project memory setup: 9P.md or an Obsidian-style vault
+ *   9p map            generate/refresh codebase wiki notes in the vault
+ *   9p serve [port]   local web session (used standalone and by the VS Code extension)
+ */
+import { runRepl } from "./repl.js";
+import { runInit } from "./init.js";
+import { runMap } from "./map.js";
+import { runServe } from "./serve.js";
+import { runLogin, runLoginPaste, runLogout } from "./login.js";
+const cwd = process.cwd();
+const args = process.argv.slice(2);
+const cmd = args[0];
+switch (cmd) {
+    case "login":
+        await (args.includes("--paste") ? runLoginPaste() : runLogin());
+        break;
+    case "logout":
+        await runLogout();
+        break;
+    case "init":
+        await runInit(cwd);
+        break;
+    case "map":
+        await runMap(cwd);
+        break;
+    case "serve": {
+        const port = Number(args[1] ?? process.env.NINEP_PORT ?? 4310);
+        await runServe(cwd, port);
+        break;
+    }
+    case "--plain":
+        await runRepl(cwd);
+        break;
+    case undefined:
+        if (process.stdout.isTTY && process.stdin.isTTY) {
+            const { runTui } = await import("./tui/index.js");
+            await runTui(cwd);
+        }
+        else {
+            await runRepl(cwd);
+        }
+        break;
+    default:
+        console.error(`unknown command: ${cmd}\nusage: 9p [login|logout|init|map|serve [port]|--plain]`);
+        process.exit(1);
+}
+//# sourceMappingURL=main.js.map

package/dist/map.d.ts

@@ -0,0 +1,2 @@
+/** `9p map`: generate/refresh graphify-style codebase wiki notes in the vault. */
+export declare function runMap(cwd: string): Promise<void>;

package/dist/map.js

@@ -0,0 +1,57 @@
+import { AgentSession, resolveVault } from "@9thprotocol/agent-core";
+import { cyan, dim, red, requireAuth, usageLine, DEFAULT_MODEL, fetchCatalog } from "./shared.js";
+function mapPrompt(vault) {
+    return `Map this codebase into the vault's graph section so future sessions can navigate the map instead of re-reading raw files.
+
+1. Explore the project with glob/grep/read: layout, packages/modules, entry points, configs.
+2. Write concise wiki notes (each under 60 lines) into ${vault}/graph/:
+   - index.md, the entry point: one line per note with a [[wiki link]] and what it covers
+   - one note per major module/package/area: purpose, key files with paths, how it connects to the rest, [[wiki links]] to related notes
+3. If a note already exists, update it in place rather than duplicating.
+4. Update ${vault}/INDEX.md so it links to graph/index (only if not already linked).
+
+Return a one-paragraph summary of what you mapped.`;
+}
+/** `9p map`: generate/refresh graphify-style codebase wiki notes in the vault. */
+export async function runMap(cwd) {
+    const vault = resolveVault(cwd);
+    if (!vault) {
+        console.error(red("No vault configured.") + ` Run ${cyan("9p init")} and choose the vault option first.`);
+        process.exit(1);
+    }
+    const auth = await requireAuth();
+    const catalog = await fetchCatalog(auth);
+    const session = new AgentSession({
+        apiKey: auth.apiKey,
+        ...(auth.platform ? { platform: auth.platform } : {}),
+        model: process.env.NINEP_MODEL ?? DEFAULT_MODEL,
+        // Mapping is bulk read-and-summarise across a whole repo, economy by design.
+        autoRouter: { bias: "economy", ...(catalog ? { catalog } : {}) },
+        cwd,
+        // writes auto-allowed (the prompt constrains them to the vault); bash denied, mapping is read+write only
+        mode: "accept-edits",
+        decide: async () => false,
+    });
+    console.log(cyan("9p map") + dim(`, mapping ${cwd} → ${vault}/graph (model: ${session.model})`));
+    for await (const ev of session.send(mapPrompt(vault))) {
+        switch (ev.type) {
+            case "text_delta":
+                process.stdout.write(ev.text);
+                break;
+            case "tool_start":
+                console.log(dim(`⚙ ${ev.summary}`));
+                break;
+            case "tool_end":
+                if (ev.isError)
+                    console.log(dim(`  ✗ ${ev.output.split("\n")[0] ?? ""}`));
+                break;
+            case "turn_end":
+                console.log(`\n${dim("⏺ " + usageLine(ev.usage))}`);
+                break;
+            case "error":
+                console.error(red(`\nerror: ${ev.message}`));
+                process.exitCode = 1;
+        }
+    }
+}
+//# sourceMappingURL=map.js.map

package/dist/repl.d.ts

@@ -0,0 +1 @@
+export declare function runRepl(cwd: string): Promise<void>;