@orlan-maker/cli 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "orlan",
+  "description": "The Orlan plugin for Claude Code.",
+  "owner": {
+    "name": "Orlan",
+    "url": "https://orlan.app"
+  },
+  "plugins": [
+    {
+      "name": "orlan",
+      "source": "./",
+      "description": "The Orlan review board in Claude Code: the orlan command, a monitor, hooks, skills and the MCP server."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "orlan",
+  "displayName": "Orlan",
+  "version": "0.1.0",
+  "description": "Work with the Orlan review board: the orlan command, a monitor that wakes the session when a person mentions the agent, hooks that show the session's state on the board, the skills, and the MCP server.",
+  "author": {
+    "name": "Orlan",
+    "url": "https://orlan.app"
+  },
+  "homepage": "https://orlan.app",
+  "repository": "https://github.com/AliProgrammin/orlan-plugin",
+  "keywords": ["review", "board", "comments", "powerpoint", "pdf"],
+  "license": "MIT"
+}

package/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "orlan": {
+      "type": "http",
+      "url": "${ORLAN_SERVER:-https://orlan.app}/mcp",
+      "headersHelper": "\"${CLAUDE_PLUGIN_ROOT}/bin/orlan\" mcp headers --agent claude-code"
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orlan
+
+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,179 @@
+# @orlan-maker/cli
+
+The `orlan` command connects an AI agent to [Orlan](https://orlan.app), the review board for decks,
+PDFs, images and HTML. The agent then reads the comments on a file, posts a new version, replies and
+resolves, from the terminal or over MCP.
+
+Needs Node 22.18 or later.
+
+## Set up
+
+In Orlan, open the organisation menu, choose **Connect an agent**, and copy the prompt for your agent.
+The prompt runs these four commands:
+
+```
+npm i -g @orlan-maker/cli
+orlan auth login
+orlan skills add --agent claude-code
+orlan mcp connect --agent claude-code
+```
+
+- `orlan auth login` shows a code and opens the approval page in your browser. Sign in, check the
+  code, choose the organisation, and the topics and role your agents get. The command waits for the
+  approval (codes work for 10 minutes). The CLI token goes to the OS keychain (macOS keychain, or the
+  Secret Service on Linux), else to `credentials.json` in the config folder, readable by you only.
+  `--server <url>` signs in to another Orlan server; `--no-browser` only prints the address.
+- `orlan skills add` writes the skills `orlan-review` and `orlan-versions` where the agent reads skills.
+- `orlan mcp connect` makes an agent token and adds the Orlan MCP server to the agent. Only an admin of
+  the organisation connects agents. For Claude Code it also installs the Orlan plugin (below);
+  `--no-plugin` adds only the MCP server.
+- `orlan status` shows who you are, the server, and each connected agent, and tests each agent's MCP
+  connection. It ends with exit code 1 when a check fails.
+
+Agents: `claude-code`, `codex`, `cursor`, `opencode`, `other`.
+
+| Agent | Skills | MCP entry |
+| --- | --- | --- |
+| claude-code | `~/.claude/skills` | `claude mcp add --transport http --scope user orlan ...` |
+| codex | `~/.agents/skills` | `[mcp_servers.orlan]` in `~/.codex/config.toml` |
+| cursor | `~/.cursor/skills` | `mcpServers.orlan` in `~/.cursor/mcp.json` |
+| opencode | `~/.config/opencode/skills` | `mcp.orlan` in `~/.config/opencode/opencode.json`, and the plugin in `~/.config/opencode/plugins/orlan.js` |
+| other | `.agents/skills` in the folder you are in | `orlan mcp print` prints the address and the header |
+
+Without `--agent`, the CLI finds the agent that runs it from its environment.
+
+## The Claude Code plugin
+
+This package is also the Claude Code plugin `orlan@orlan`. Its public marketplace is
+https://github.com/AliProgrammin/orlan-plugin (MIT). Install it in two lines:
+
+```
+claude plugin marketplace add AliProgrammin/orlan-plugin
+claude plugin install orlan@orlan
+```
+
+`orlan mcp connect --agent claude-code` installs it too; from a checkout,
+`claude plugin marketplace add ./packages/cli` and `claude plugin install orlan@orlan` do the same. One install gives the session:
+
+- `orlan` on the PATH of Claude Code's shell.
+- A monitor that runs `orlan wait --follow`: a mention of the agent wakes the session, also when it is
+  idle. Monitors run only in an interactive session.
+- Hooks that show the session on the board: working (session start, a prompt, each tool), waiting for
+  input (a permission prompt or a question in the terminal), idle (the turn ended), done (the session
+  ended). At the session start, `orlan brief` goes into the session's context.
+- The skills `orlan-review` and `orlan-versions`.
+- The Orlan MCP server. Its header comes from `orlan mcp headers`, with the token from the keychain. It
+  goes to `$ORLAN_SERVER`, else https://orlan.app: on another server, set `ORLAN_SERVER` where you start
+  Claude Code.
+
+## The OpenCode plugin
+
+`orlan mcp connect --agent opencode` also writes the Orlan plugin to `~/.config/opencode/plugins/orlan.js`.
+When a session's turn ends, the plugin runs `orlan hook wait`. A mention of the agent on the board then goes
+to the session as a new prompt, and a new turn starts. The plugin also shows the session on the board:
+working, waiting for a permission prompt, idle, done. A request wakes a session only while OpenCode runs
+(the TUI or `opencode serve`). Restart a running OpenCode to load the plugin. `orlan mcp disconnect
+--agent opencode` removes it.
+
+## Daily commands
+
+Each works as the connected agent, with the agent's own token, and is in the topic's audit log. Each
+is plain HTTP with the agent token, with no MCP session: `orlan files push` makes 2 requests (the file,
+then the post), `orlan files pull` 2 (the file's answer, then the download), and most others 1.
+
+```
+orlan brief [--topic <topic>]
+orlan topics list
+orlan files list --topic <topic>
+orlan files add <path> [--topic <topic>]
+orlan files pull <file> [--version <n>] [--topic <topic>] [--out <path>] [--edit [--shared] [--ttl <time>]]
+orlan files push <file> <path> --changelog "<what changed>" [--base <n>] [--topic <topic>]
+orlan comments list [--topic <topic>] [--status open|resolved|all] [--file <file>]
+orlan comment <thread> "<text>" | --file <file> --page <n> [--region <x,y,w,h>] "<text>" | --at <x,y> "<text>" [--topic <topic>]
+orlan comments resolve <thread> [--topic <topic>]
+orlan open [<topic id>] [--file <file id>]
+orlan wait [--follow]
+orlan inbox [--new]
+orlan inbox done <request id>
+orlan respond <request id> --message "<text>" [--file <path>] [--to <file>] [--changelog "<text>"] [--base <n>] [--wait]
+orlan hook <working|needs-input|idle|done>
+orlan hook start|stop --agent codex|cursor
+orlan mcp headers
+```
+
+The ids people see work as input: a topic by its name, a file by its name, a thread as `#12`, and a
+version as `v5` (or `5`). A name or a number is looked up on `--topic`, else on every topic of the
+agent. When it matches more than one, the command stops with a plain error that lists each match with
+its id and topic: give the id, or add `--topic`.
+
+Every output ends with a `next_step` line, and every error says what to do next in a `next_step` line.
+With `--json`, a command prints small JSON on one line with a `next_step` field; an error is JSON too:
+`{"error": "<code>", "message": "...", "next_step": "..."}`. The hook commands and `orlan mcp headers`
+print only what their harness reads, and `orlan inbox --new` prints nothing when there is no request.
+
+`orlan brief` is for the start of a session. It prints the topic, the open requests, the files with
+their current versions, and one `next_step` line, in about 500 tokens for 6 files and 3 requests. The
+topic is the one the agent used last, else its only topic. `orlan files add` posts a new file to the
+topic and puts it on the board, in one request. Both are plain HTTP calls with the agent token, with
+no MCP session.
+
+`orlan comment` replies in a thread, or opens a new thread: with `--file` and `--page` on a page (the
+whole page, or `--region` as fractions of the page), with `--at` on a point of the board. People see it
+on the board at once. "@" and a name mentions a person or an agent of the topic. A mention of another
+agent makes no request when that agent still has an open request from you in the thread, or after 5 asks
+this hour: the command prints "Not asked: <name>".
+
+`orlan wait` waits for the next request to the agent: a person, a guest or an agent mentions it in a
+comment. It prints the request with each comment, its file, version, page, region, the text under the
+region and a crop link, and exits. Running it again after a lost connection is safe: the request comes
+once. The wait confirms each request after it printed it; when the wait stops before that, the request
+goes back to the inbox within 20 seconds. `--follow` stays open and prints one line per request. `orlan inbox` prints the open requests;
+`--new` takes the new ones and prints nothing when there are none, for a stop hook. `orlan inbox done`
+closes a request when its work is finished.
+
+`orlan files pull --edit` puts the agent's claim on the file: other agents get it in their answer,
+and the board shows "Claude (for Sara) is editing from v4 - 3 min" on the file. The claim warns and
+blocks nothing. It lasts 15 minutes (`--ttl 90s`, `--ttl 1h`), and a push or respond of the agent ends
+it. When another agent has a claim, the pull gives no claim and a `next_step`: wait for its version,
+ask it with `orlan comment`, or take a shared claim with `--edit --shared`. A push or respond names its
+base version: `--base`, else the version the pull got, else (respond) the version the comments were on.
+When a newer version landed first, Orlan refuses it with `stale_base`, the newer changelog and a
+`next_step`, and nothing changes.
+
+`orlan respond` closes a review round in one command. With `--file`, it posts the file as a new version
+of the file the request is about, with the version the comments were on as its base (`--to <file id>`
+when the request names no file or several). Then it replies with the message in each thread of the
+request, resolves the threads, and marks the request done. `--wait` then waits for the next request, as
+`orlan wait` does. A request that is done already gives a refusal and a `next_step` line. To ask a
+person a question, reply with `orlan comment` and leave the thread open: the answer comes to the
+inbox as a request. A request that stays taken for 10 minutes with no done goes back to the inbox.
+
+`orlan hook` is for harness hooks, not for the model: it tells the board that the agent works, waits
+in the terminal (for example on a permission prompt), is idle or is done. It reads the hook's JSON on
+standard input, makes one request, prints nothing and makes no model call. Orlan never answers the
+terminal prompt; the board tells people to go to the terminal. With no agent connected, it does nothing.
+
+`orlan hook start` and `orlan hook stop` are the session start and stop hooks of Codex and Cursor, and
+`orlan mcp connect --agent codex|cursor` installs them. Codex and Cursor sessions do not wake when idle:
+the start hook puts the brief in the session, and when a turn ends the stop hook gives the session the
+new requests, so it works on at once. After 5 requests in a row it lets the session stop. Codex runs a
+hook only after you trust it once with `/hooks`.
+
+`orlan mcp headers` prints the MCP authorization header as JSON, for a `headersHelper`. The plugin's MCP
+server runs it.
+
+While a wait of the agent is open (the plugin's monitor), the `next_step` lines do not say `--wait`:
+the open wait gets the next request.
+
+A version the agent posts waits for a person to make it current. When several agents are connected,
+add `--agent <id>`.
+
+## Stop
+
+- `orlan mcp disconnect --agent <id>` revokes the agent's token and removes its MCP entry.
+- `orlan auth logout` revokes the CLI token. You can also revoke it in Orlan: Profile, Orlan CLI sign-ins.
+
+Run `orlan help` for every command, and `orlan <command> --help` for its options.
+
+Settings: `ORLAN_SERVER` names the server, `ORLAN_CONFIG_DIR` the config folder, `ORLAN_KEYCHAIN=off`
+keeps secrets in the file, and `BROWSER` names the program that opens the approval page.

package/bin/orlan

@@ -0,0 +1,8 @@
+#!/bin/sh
+# The orlan command of the Claude Code plugin (F044). Claude Code puts this folder on the PATH of its
+# shell. It runs the CLI of this package: the sources in a checkout, else the build the npm package has.
+root=$(cd "$(dirname "$0")/.." && pwd)
+if [ -f "$root/src/main.ts" ]; then
+  exec node "$root/src/main.ts" "$@"
+fi
+exec node "$root/dist/main.js" "$@"

package/dist/agents.js

@@ -0,0 +1,406 @@
+/**
+ * The agents the CLI connects: where each one reads skills, and how its MCP settings get the Orlan
+ * server. The ids match the web app's connect dialog (agentClients in @orlan/shared).
+ */
+import { execFile } from "node:child_process";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { OrlanError } from "./http.js";
+export const agentIds = ["claude-code", "codex", "cursor", "opencode", "other"];
+export const agentLabels = {
+    "claude-code": "Claude Code",
+    codex: "Codex",
+    cursor: "Cursor",
+    opencode: "OpenCode",
+    other: "your agent",
+};
+/** The MCP server name in each agent's settings. */
+export const MCP_NAME = "orlan";
+export function parseAgent(value) {
+    if (agentIds.includes(value))
+        return value;
+    throw new OrlanError(`"${value}" is not an agent Orlan knows. Use one of: ${agentIds.join(", ")}.`);
+}
+/** Environment variables each agent sets for the commands it runs. */
+const markers = [
+    ["claude-code", ["CLAUDECODE"]],
+    ["codex", ["CODEX_SANDBOX", "CODEX_SANDBOX_NETWORK_DISABLED", "CODEX_THREAD_ID"]],
+    ["opencode", ["OPENCODE"]],
+    ["cursor", ["CURSOR_AGENT", "CURSOR_TRACE_ID"]],
+];
+/** The agent that runs this command, from its environment, or undefined. */
+export function detectAgent(env = process.env) {
+    return markers.find(([, names]) => names.some((name) => env[name]))?.[0];
+}
+const home = () => homedir();
+const xdgConfig = () => process.env.XDG_CONFIG_HOME || path.join(home(), ".config");
+/**
+ * The folder each agent reads skills from. "other" gets them in the project folder. Checked against
+ * each tool's documentation on 2026-09-24 (B018):
+ * - Codex: user skills in $HOME/.agents/skills - https://learn.chatgpt.com/docs/build-skills
+ *   (was https://developers.openai.com/codex/skills)
+ * - Cursor: user skills in ~/.cursor/skills (it reads ~/.agents/skills too) -
+ *   https://cursor.com/docs/context/skills
+ * - OpenCode: global skills in ~/.config/opencode/skills/<name>/SKILL.md -
+ *   https://opencode.ai/docs/skills/
+ */
+export function skillsDir(agent, cwd = process.cwd()) {
+    switch (agent) {
+        case "claude-code":
+            return path.join(process.env.CLAUDE_CONFIG_DIR || path.join(home(), ".claude"), "skills");
+        case "codex":
+            return path.join(home(), ".agents", "skills");
+        case "cursor":
+            return path.join(home(), ".cursor", "skills");
+        case "opencode":
+            return path.join(xdgConfig(), "opencode", "skills");
+        case "other":
+            return path.join(cwd, ".agents", "skills");
+    }
+}
+/**
+ * The MCP settings file of an agent that has one the CLI edits. Checked against each tool's
+ * documentation on 2026-09-24 (B018):
+ * - Codex: `[mcp_servers.<name>]` with `url` and `http_headers` in ~/.codex/config.toml -
+ *   https://learn.chatgpt.com/docs/extend/mcp?surface=cli (was https://developers.openai.com/codex/mcp)
+ * - Cursor: `mcpServers.<name>` with `url` and `headers` in ~/.cursor/mcp.json (the editor and the
+ *   cursor-agent CLI read it) - https://cursor.com/docs/context/mcp and https://cursor.com/docs/cli/mcp
+ * - OpenCode: `mcp.<name>` with `type: "remote"`, `url`, `headers` and `enabled` in
+ *   ~/.config/opencode/opencode.json - https://opencode.ai/docs/mcp-servers/ and
+ *   https://opencode.ai/docs/config/
+ */
+export function mcpFile(agent) {
+    switch (agent) {
+        case "codex":
+            return path.join(process.env.CODEX_HOME || path.join(home(), ".codex"), "config.toml");
+        case "cursor":
+            return path.join(home(), ".cursor", "mcp.json");
+        case "opencode":
+            return path.join(xdgConfig(), "opencode", "opencode.json");
+    }
+}
+async function readText(file) {
+    try {
+        return await readFile(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "";
+        throw error;
+    }
+}
+/** Writes the file at once. The file holds a secret, so only this user reads it. */
+async function writeText(file, text) {
+    await mkdir(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    await writeFile(temporary, text, { mode: 0o600 });
+    await rename(temporary, file);
+}
+/** A TOML table header line such as `[mcp_servers.orlan]` or `[[x]]`, with its dotted name. */
+const tableHeader = (line) => /^\s*\[\[?\s*([^\]]+?)\s*\]\]?\s*(#.*)?$/.exec(line)?.[1];
+/**
+ * The Codex config.toml without the `[mcp_servers.orlan]` table and its sub-tables, and with the new
+ * one when `entry` is given. Every other line stays as it was, comments too.
+ */
+export function editCodexToml(text, entry) {
+    const lines = text.split("\n");
+    const kept = [];
+    let inOrlan = false;
+    for (const line of lines) {
+        const header = tableHeader(line);
+        if (header !== undefined) {
+            const name = header.replace(/\s/g, "").replace(/"/g, "");
+            inOrlan = name === `mcp_servers.${MCP_NAME}` || name.startsWith(`mcp_servers.${MCP_NAME}.`);
+        }
+        if (!inOrlan)
+            kept.push(line);
+    }
+    let result = kept.join("\n").replace(/\n+$/, "");
+    if (entry) {
+        const table = [
+            `[mcp_servers.${MCP_NAME}]`,
+            `url = ${JSON.stringify(entry.url)}`,
+            `http_headers = { "Authorization" = ${JSON.stringify(entry.authorization)} }`,
+        ].join("\n");
+        result = result ? `${result}\n\n${table}` : table;
+    }
+    return result ? `${result}\n` : "";
+}
+/** Sets or removes one key in a JSON settings file, under `section`. */
+async function editJson(file, section, value) {
+    const text = await readText(file);
+    let settings;
+    try {
+        settings = text.trim() ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new OrlanError(`${file} is not plain JSON (it has comments or an error), so Orlan does not change it. ` +
+            "Run `orlan mcp print` and add the entry by hand.");
+    }
+    const servers = { ...(settings[section] ?? {}) };
+    if (value === undefined) {
+        if (!(MCP_NAME in servers))
+            return;
+        delete servers[MCP_NAME];
+    }
+    else {
+        servers[MCP_NAME] = value;
+    }
+    settings[section] = servers;
+    await writeText(file, `${JSON.stringify(settings, null, 2)}\n`);
+}
+function runClaude(args) {
+    return new Promise((resolve, reject) => {
+        execFile("claude", args, { timeout: 60_000 }, (error, stdout, stderr) => {
+            if (error && error.code === "ENOENT") {
+                reject(new OrlanError("Orlan cannot find the `claude` command. Install Claude Code first."));
+                return;
+            }
+            resolve({ ok: !error, output: `${stdout}${stderr}`.trim() });
+        });
+    });
+}
+/**
+ * The Claude Code plugin (F044). This package is the plugin and its own marketplace: the folder with
+ * package.json has .claude-plugin/plugin.json and .claude-plugin/marketplace.json. A local marketplace
+ * loads the plugin in place, so an update of the package updates the plugin.
+ */
+export const CLAUDE_PLUGIN = "orlan@orlan";
+const packageRoot = () => fileURLToPath(new URL("..", import.meta.url));
+/** True when the Orlan plugin is installed and enabled in Claude Code. */
+async function claudePluginEnabled() {
+    const listed = await runClaude(["plugin", "list", "--json"]);
+    if (!listed.ok)
+        return false;
+    try {
+        const plugins = JSON.parse(listed.output);
+        return Array.isArray(plugins) && plugins.some((plugin) => plugin.id === CLAUDE_PLUGIN && plugin.enabled);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Installs the Orlan plugin in Claude Code for this user, from this package, when it is not enabled
+ * yet. Returns false when Claude Code refused the install.
+ */
+export async function installClaudePlugin() {
+    if (await claudePluginEnabled())
+        return true;
+    await runClaude(["plugin", "marketplace", "add", packageRoot(), "--scope", "user"]);
+    const installed = await runClaude(["plugin", "install", CLAUDE_PLUGIN, "--scope", "user"]);
+    return installed.ok && (await claudePluginEnabled());
+}
+/**
+ * The hooks file of Codex and Cursor (F046). Checked against each tool's documentation on 2026-09-26:
+ * - Codex: $CODEX_HOME/hooks.json (default ~/.codex), events SessionStart, UserPromptSubmit,
+ *   PermissionRequest, PostToolUse and Stop. A person trusts each hook once with /hooks, and Codex keeps
+ *   the trust by file, event and position - https://learn.chatgpt.com/docs/hooks
+ * - Cursor: ~/.cursor/hooks.json with `version: 1`, events sessionStart, beforeSubmitPrompt, stop and
+ *   sessionEnd. The editor and the cursor-agent CLI read it - https://cursor.com/docs/hooks
+ */
+export function hooksFile(agent) {
+    return agent === "codex"
+        ? path.join(process.env.CODEX_HOME || path.join(home(), ".codex"), "hooks.json")
+        : path.join(home(), ".cursor", "hooks.json");
+}
+/**
+ * How many requests in a row a stop hook gives one session before it lets the session stop. Codex has
+ * no limit of its own. Cursor drops a hook's follow-up at its loop_limit, 5 by default, which Orlan
+ * writes too. Orlan takes no request past this limit, so it never takes a request the harness drops.
+ */
+export const STOP_LOOP_LIMIT = 5;
+/** A hook command Orlan wrote ends with `hook <state> --agent codex` or `--agent cursor`. */
+const orlanHookCommand = /\shook (start|stop|working|needs-input|idle|done) --agent (codex|cursor)$/;
+/**
+ * The command a hook runs: this Node and this CLI by full path, because a harness started from the
+ * desktop (Cursor, the Codex app) often has no `orlan` or `node` on its PATH.
+ */
+function hookCommand(args) {
+    return `${JSON.stringify(process.execPath)} ${JSON.stringify(cliMain())} hook ${args}`;
+}
+/** The main file of this CLI: src/main.ts in a checkout, dist/main.js in the npm package. */
+function cliMain() {
+    const source = fileURLToPath(import.meta.url);
+    return path.join(path.dirname(source), `main${path.extname(source)}`);
+}
+/** The Orlan hooks of each harness, by event, in the shape of its hooks.json. */
+function orlanHooks(agent) {
+    if (agent === "codex") {
+        const entry = (args, timeout, statusMessage) => ({
+            hooks: [
+                {
+                    type: "command",
+                    command: hookCommand(`${args} --agent codex`),
+                    timeout,
+                    ...(statusMessage ? { statusMessage } : {}),
+                },
+            ],
+        });
+        return {
+            SessionStart: entry("start", 10, "Reading the Orlan brief"),
+            UserPromptSubmit: entry("working", 5),
+            PermissionRequest: entry("needs-input", 5),
+            PostToolUse: entry("working", 5),
+            Stop: entry("stop", 10, "Checking Orlan for requests"),
+        };
+    }
+    const entry = (args, timeout, more = {}) => ({
+        command: hookCommand(`${args} --agent cursor`),
+        timeout,
+        ...more,
+    });
+    return {
+        sessionStart: entry("start", 10),
+        beforeSubmitPrompt: entry("working", 5),
+        stop: entry("stop", 10, { loop_limit: STOP_LOOP_LIMIT }),
+        sessionEnd: entry("done", 5),
+    };
+}
+/** True for a hook entry Orlan wrote: a Cursor entry with an Orlan command, or a Codex group with one. */
+function isOrlanHook(entry) {
+    if (!entry || typeof entry !== "object")
+        return false;
+    const { command, hooks } = entry;
+    if (typeof command === "string")
+        return orlanHookCommand.test(command);
+    return Array.isArray(hooks) && hooks.some(isOrlanHook);
+}
+/**
+ * The hooks.json settings with the Orlan hooks of `add` in place of the old ones, or with no Orlan
+ * hooks when `add` is undefined. Every other hook stays at its place, and an Orlan hook goes back to
+ * its place: Codex keeps a person's trust by the position of the hook.
+ */
+export function editHooks(settings, add) {
+    const events = { ...(settings.hooks ?? {}) };
+    for (const event of new Set([...Object.keys(events), ...Object.keys(add ?? {})])) {
+        const current = events[event] ?? [];
+        // Not a list of hooks: not a shape Orlan writes, so it stays as it is.
+        if (!Array.isArray(current))
+            continue;
+        const at = current.findIndex(isOrlanHook);
+        const kept = current.filter((entry) => !isOrlanHook(entry));
+        const mine = add?.[event];
+        if (mine)
+            kept.splice(at === -1 ? kept.length : at, 0, mine);
+        if (kept.length > 0)
+            events[event] = kept;
+        else
+            delete events[event];
+    }
+    return { ...settings, hooks: events };
+}
+/** Writes the Orlan hooks into the harness's hooks.json, or takes them out. Returns the file. */
+export async function setHooks(agent, install) {
+    const file = hooksFile(agent);
+    const text = await readText(file);
+    if (!text.trim() && !install)
+        return file;
+    let settings;
+    try {
+        settings = text.trim() ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new OrlanError(`${file} is not plain JSON, so Orlan does not change it. Correct the file, then run this again.`);
+    }
+    const edited = editHooks(settings, install ? orlanHooks(agent) : undefined);
+    await writeText(file, `${JSON.stringify(agent === "cursor" ? { version: 1, ...edited } : edited, null, 2)}\n`);
+    return file;
+}
+/**
+ * The Orlan plugin of OpenCode (F045), in its global plugins folder: ~/.config/opencode/plugins/ -
+ * https://opencode.ai/docs/plugins/ (checked 2026-09-27 against OpenCode 1.18.30).
+ */
+export function opencodePluginFile() {
+    return path.join(xdgConfig(), "opencode", "plugins", "orlan.js");
+}
+/** The first line of the plugin, so a disconnect removes only a file Orlan wrote. */
+const OPENCODE_PLUGIN_MARK = "// The Orlan plugin for OpenCode (F045).";
+/**
+ * The plugin as `orlan mcp connect` writes it: opencode/orlan.js of this package, with this Node and
+ * this CLI by full path in place of `orlan` on the PATH.
+ */
+export async function opencodePlugin() {
+    const source = await readFile(path.join(packageRoot(), "opencode", "orlan.js"), "utf8");
+    const line = 'const ORLAN = ["orlan"];';
+    if (!source.startsWith(OPENCODE_PLUGIN_MARK) || !source.includes(line)) {
+        throw new OrlanError("The OpenCode plugin of this orlan package is damaged. Install @orlan-maker/cli again.");
+    }
+    return source.replace(line, `const ORLAN = ${JSON.stringify([process.execPath, cliMain()])};`);
+}
+/** Writes the Orlan plugin into OpenCode's plugins folder, or takes it out. Returns the file. */
+export async function setOpencodePlugin(install) {
+    const file = opencodePluginFile();
+    if (install) {
+        await writeText(file, await opencodePlugin());
+    }
+    else if ((await readText(file)).startsWith(OPENCODE_PLUGIN_MARK)) {
+        await rm(file, { force: true });
+    }
+    return file;
+}
+/**
+ * Writes the Orlan MCP server into the agent's settings, in place of an older entry. Returns what it
+ * changed, for the person.
+ */
+export async function addMcp(agent, url, secret) {
+    const authorization = `Bearer ${secret}`;
+    switch (agent) {
+        case "claude-code": {
+            await runClaude(["mcp", "remove", MCP_NAME, "--scope", "user"]);
+            const added = await runClaude([
+                "mcp",
+                "add",
+                "--transport",
+                "http",
+                "--scope",
+                "user",
+                MCP_NAME,
+                url,
+                "--header",
+                `Authorization: ${authorization}`,
+            ]);
+            if (!added.ok)
+                throw new OrlanError(`claude mcp add failed: ${added.output.replaceAll(secret, "orl_...")}`);
+            return "Claude Code (claude mcp add --scope user)";
+        }
+        case "codex": {
+            const file = mcpFile("codex");
+            await writeText(file, editCodexToml(await readText(file), { url, authorization }));
+            return file;
+        }
+        case "cursor": {
+            const file = mcpFile("cursor");
+            await editJson(file, "mcpServers", { url, headers: { Authorization: authorization } });
+            return file;
+        }
+        case "opencode": {
+            const file = mcpFile("opencode");
+            await editJson(file, "mcp", { type: "remote", url, headers: { Authorization: authorization }, enabled: true });
+            return file;
+        }
+    }
+}
+/** Takes the Orlan MCP server out of the agent's settings. */
+export async function removeMcp(agent) {
+    switch (agent) {
+        case "claude-code":
+            await runClaude(["mcp", "remove", MCP_NAME, "--scope", "user"]);
+            return;
+        case "codex": {
+            const file = mcpFile("codex");
+            const text = await readText(file);
+            if (text)
+                await writeText(file, editCodexToml(text));
+            return;
+        }
+        case "cursor":
+            await editJson(mcpFile("cursor"), "mcpServers", undefined);
+            return;
+        case "opencode":
+            await editJson(mcpFile("opencode"), "mcp", undefined);
+            return;
+    }
+}