"note": "Heuristic false-green LEADS, not findings. A finding requires a demonstrated reproduction (surviving mutation via mutation-runner). Do not treat a candidate as a confirmed false green. Coverage-theater leads may include tests that delegate their assertion to a custom helper the classifier does not recognise; verify before acting.",

  "sourceDigest": "sha256:dd810dd48c5bdbc9becd7fcc01dd41a4ca2abf0b2d6f6a545907247f6e3e8361",

  "summary": {

    "filesScanned": 2433,

    "filesScanned": 2434,

    "candidateCount": 16,

    "byMode": {

      "false_green_coverage_theater": 15,

{

  "schemaVersion": "1",

  "repository": "OpenAgentsInc/openagents",

  "sourceDigest": "sha256:4850da44cf6c8cacbc5ec66d9405156d05c9008aed2fd97dbe17d9492041dec8",

  "sourceDigest": "sha256:148589c7a0eaf2212132813961369d469f43d46e01a7ed722b0b458abb9ca63c",

  "surfaces": [

    {

      "id": "app:@openagentsinc/acceptance-runner",

      "oracles": [

        {

          "type": "test",

          "ref": "packages/openagents-cli (33 tracked test files)"

          "ref": "packages/openagents-cli (34 tracked test files)"

        },

        {

          "type": "behavior-contract",

  "files": [

    "dist",

    "contracts",

    "README.md"

    "README.md",

    "skills"

  ],

  "type": "module",

  "sideEffects": false,

---

name: openagents-cli

description: Use the OpenAgents CLI to read and write issues, projects, repositories, and the forum, to call any API route, and to sign a person in. Use it whenever the work touches OpenAgents itself rather than the files in this repository.

---

# The OpenAgents CLI

You are running inside `openagents coder`, which is one subcommand of the

`openagents` CLI. The `openagents` tool runs the rest of it. The same binary

answers, so what you see is this machine's build, not a remembered one.

## Find out what a command does by asking it

Every command documents itself. `openagents --help` lists the subcommands;

`openagents <command> --help` gives one command's flags and arguments;

`openagents <command> <subcommand> --help` goes a level deeper.

Ask before you guess. This file deliberately does not list flags: a written

copy of them goes stale the first time one changes, and the help output cannot.

Add `--json` to any command to get the response as JSON rather than as prose.

Prefer it when you are going to read a field out of the answer.

## What works with no credential

- `openagents computer probe|policy|status` — inspects this machine. The local

  machine controls all access; no account is involved.

- `openagents coder --offline` — answers from a built-in stand-in.

- `--help` anywhere.

Everything else reaches the API and needs a token. Without one you get:

```

openagents: No OpenAgents token is available for https://openagents.com.

Set OPENAGENTS_TOKEN.

```

Read that as "this person is not signed in", not as a broken command.

## What signing in involves

A token is per API origin, stored in the OS credential store, and carries

scopes. Two matter:

- `chat:account` — open a thread and talk to a model.

- `forge:write` — push to the forge and write to issues, projects, and the

  forum.

An ordinary sign-in mints both. Do not ask for one scope on its own: a token

minted for `chat:account` alone cannot push, and one minted for `forge:write`

alone cannot open a thread, and each failure arrives a command later where it

reads as the product being broken.

Check with `openagents auth status`, which names the account, the eligible

namespaces, and the expiry without printing the token.

### Signing a person in

You cannot complete this for them; it needs a browser and their approval.

1. Run `openagents auth login --headless`. It returns a URL and a short code

   and does not block.

2. Give the person the URL and the code, and say what they are approving: this

   CLI, on this machine, for their OpenAgents account.

3. When they say they have approved it, run `openagents auth login --resume`.

4. Confirm with `openagents auth status`.

Tell them what it is for in a sentence — "so the CLI can push to the forge and

open a thread" — rather than only handing over a link. A person asked to

approve something unexplained is right to refuse.

Never print a token, and never paste one into a file, a commit message, or an

issue.

## Reaching a route with no command

`openagents api <path>` sends an authenticated request to any API route and

writes the body as JSON. A path without a leading slash resolves under

`/api/v3/`. Use it when no named command covers what you need — several routes

have no command of their own.

## Two cautions

**You are already a coder session.** Do not start another one. To run work in

parallel, use the `delegate` tool, which is what it is for.

**Writes are real.** Closing an issue, posting to the forum, or pushing to a

repository is visible to other people immediately and is not yours to undo. Say

what you are about to write and get agreement before a first write in a

session. Reads need no ceremony.

  parseOllamaModelFlag,

} from "./coder-ollama.js";

import { openThread, ThreadUnavailable, type ThreadReplySource } from "./coder-thread.js";

import { delegateTool, skillTool } from "./coder-tools.js";

import { delegateTool, openagentsTool, skillTool } from "./coder-tools.js";

import { spawnSync } from "node:child_process";

import { rebuild, RELOAD_EXIT_CODE, sourceCheckout } from "./coder-reload.js";

        const active = skills.active();

        const tools = [

          ...(active.length === 0 ? [] : [skillTool(active)]),

          openagentsTool(),

          ...(setup === undefined ? [] : [delegateTool(setup.delegation)]),

        ];

        source.useTools?.(tools);

import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";

import { homedir } from "node:os";

import { dirname, join } from "node:path";

import { fileURLToPath } from "node:url";

/** Where skills live, nearest first. A repository skill wins its name. */

const SKILL_DIRECTORIES = (cwd: string, home: string): ReadonlyArray<string> => [

/**

 * Where skills live, nearest first. The first to claim a name keeps it.

 *

 * The CLI ships its own last, so a repository or a person can replace one by

 * writing a skill of the same name and nothing has to be uninstalled. They are

 * ordinary skills otherwise: they appear in the catalog, and `/skills` switches

 * them off like any other.

 */

const SKILL_DIRECTORIES = (

  cwd: string,

  home: string,

  builtIn: string,

): ReadonlyArray<string> => [

  join(cwd, ".agents", "skills"),

  join(home, ".agents", "skills"),

  builtIn,

];

/** The skills packaged with this CLI, beside the compiled output. */

const builtInSkills = (): string =>

  join(dirname(fileURLToPath(import.meta.url)), "..", "skills");

/** How much of one skill body is handed back. */

const BODY_LIMIT = 32_000;

  cwd: string = process.cwd(),

  // Taken rather than read so a test can point at a directory it made. A

  // function that always reads the real home directory can only be tested on a

  // machine that happens to have the right skills in it.

  // machine that happens to have the right skills in it, and the same goes for

  // the directory this package ships.

  home: string = homedir(),

  builtIn: string = builtInSkills(),

): ReadonlyArray<CoderSkill> {

  const found = new Map<string, CoderSkill>();

  for (const directory of SKILL_DIRECTORIES(cwd, home)) {

  for (const directory of SKILL_DIRECTORIES(cwd, home, builtIn)) {

    let entries: ReadonlyArray<string>;

    try {

      entries = readdirSync(directory);

export function loadSkillSelection(

  cwd: string = process.cwd(),

  home: string = homedir(),

  builtIn?: string,

): SkillSelection {

  const all = discoverSkills(cwd, home);

  const all = discoverSkills(cwd, home, builtIn);

  const path = selectionPath(home);

  const disabled = new Set(readDisabled(path, cwd));

 * reads, and a function that runs on this machine.

 */

import { existsSync } from "node:fs";

import { fileURLToPath } from "node:url";

import type { CoderDelegation } from "./coder-session.js";

import { catalogEntry, renderSkill, type CoderSkill } from "./coder-skills.js";

import { describePrompt, MAX_DELEGATE_COUNT } from "./coder-delegate.js";

    },

  };

}

/**

 * How much of one command's output the model is shown.

 *

 * Enough for a help page or a page of issues. A command that produces more than

 * this is one to narrow with a flag or `--json`, not one to read whole.

 */

const CLI_OUTPUT_LIMIT = 16_000;

/** How long a command may run before it is given up on. */

const CLI_TIMEOUT_MS = 120_000;

/**

 * Commands that wait for a terminal, and what to do instead.

 *

 * The tool has no terminal to give them: a session that started one would hang

 * with nothing on screen to say why. Refused by name, with the alternative,

 * rather than left to time out.

 */

const NEEDS_A_TERMINAL: ReadonlyArray<readonly [ReadonlyArray<string>, string]> = [

  [["coder"], "You are already a coder session. Use the `delegate` tool to run work in parallel."],

  [

    ["auth", "login"],

    "Run `auth login --headless` instead: it returns a URL and a code for the person to " +

      "approve, then `auth login --resume` completes it.",

  ],

  [["computer", "up"], "It serves until stopped, so it belongs in a terminal of its own."],

];

/**

 * The compiled entry to run, in whichever layout this module is loaded from.

 *

 * Not `PATH`, and not `process.argv[1]`: what answers has to be the build this

 * session is part of, or `--help` describes a different CLI than the one

 * running. `main.js` sits beside this module in a build and one directory over

 * in a source tree, and a test runs from the second.

 */

const cliEntry = (): string | undefined => {

  for (const candidate of ["main.js", "../dist/main.js"]) {

    const path = fileURLToPath(new URL(candidate, import.meta.url));

    if (existsSync(path)) return path;

  }

  return undefined;

};

const refusalFor = (args: ReadonlyArray<string>): string | undefined => {

  const words = args.filter((word) => !word.startsWith("-"));

  for (const [prefix, alternative] of NEEDS_A_TERMINAL) {

    const matches = prefix.every((word, at) => words[at] === word);

    // `auth login --headless` does not wait, so it is not the refused command.

    if (matches && !(prefix[0] === "auth" && args.includes("--headless"))) {

      return `\`openagents ${prefix.join(" ")}\` needs a terminal, which this tool has not got. ${alternative}`;

    }

  }

  return undefined;

};

/**

 * The openagents tool: run the CLI this session is part of.

 *

 * The same binary that is running answers, found through `process.argv` rather

 * than through `PATH`, so what the model reads is this machine's build and not

 * whichever copy happens to be installed. That also means `--help` is a live

 * answer: the model discovers the command tree by asking it, and no list here

 * can go stale.

 */

export function openagentsTool(): CoderTool {

  return {

    name: "openagents",

    description:

      "Run the OpenAgents CLI: issues, projects, repositories, the forum, authentication, and " +

      "any API route through `api`. Pass the arguments after `openagents` as a list, without " +

      "`openagents` itself. Discover what exists with `--help` on any command rather than " +

      "guessing at flags, and add `--json` when you are going to read a field out of the " +

      "answer. Reads are free; a write is visible to other people at once, so say what you are " +

      "about to write before the first one. Read the `openagents-cli` skill for the auth model " +

      "and what works with no credential.",

    parameters: {

      type: "object",

      properties: {

        args: {

          type: "array",

          items: { type: "string" },

          description:

            'The arguments after `openagents`, one per element. For example ["issue", "view", ' +

            '"21", "-R", "OpenAgentsInc/openagents", "--json"].',

        },

      },

      required: ["args"],

      additionalProperties: false,

    },

    run: async (rawArgs, signal) => {

      const args = Array.isArray(rawArgs["args"])

        ? rawArgs["args"].filter((word): word is string => typeof word === "string")

        : [];

      if (args.length === 0) {

        return "No command was run: `args` is required, such as [\"--help\"].";

      }

      const refusal = refusalFor(args);

      if (refusal !== undefined) return refusal;

      const { spawn } = await import("node:child_process");

      const entry = cliEntry();

      if (entry === undefined) return "This session cannot find the CLI it is running from.";

      return await new Promise<string>((resolve) => {

        const child = spawn(process.execPath, [entry, ...args], {

          // No terminal, so a command that would prompt gets end-of-file rather

          // than a wait nobody can see.

          stdio: ["ignore", "pipe", "pipe"],

        });

        let output = "";

        let done = false;

        const finish = (text: string) => {

          if (done) return;

          done = true;

          clearTimeout(timer);

          signal.removeEventListener("abort", onAbort);

          resolve(text);

        };

        const timer = setTimeout(() => {

          child.kill("SIGKILL");

          finish(`The command did not finish within ${String(CLI_TIMEOUT_MS / 1000)}s.\n\n${output}`);

        }, CLI_TIMEOUT_MS);

        const onAbort = () => {

          child.kill("SIGKILL");

          finish("The command was interrupted.");

        };

        signal.addEventListener("abort", onAbort, { once: true });

        const collect = (chunk: Buffer) => {

          if (output.length < CLI_OUTPUT_LIMIT) output += chunk.toString("utf8");

        };

        child.stdout.on("data", collect);

        child.stderr.on("data", collect);

        child.on("error", (cause) => {

          finish(`The command could not be started: ${cause.message}`);

        });

        child.on("close", (code) => {

          const bounded =

            output.length > CLI_OUTPUT_LIMIT

              ? `${output.slice(0, CLI_OUTPUT_LIMIT)}\n\n[truncated; narrow the command or use --json]`

              : output;

          const body = bounded.trim();

          // The exit code is reported on failure because it is what the CLI

          // says about itself, and an empty failure reads as an empty success.

          finish(

            code === 0

              ? body.length === 0

                ? "The command succeeded and printed nothing."

                : body

              : `The command exited with code ${String(code ?? -1)}.\n\n${body}`,

          );

        });

      });

    },

  };

}

/** A home directory with no skills in it, so a test reads only its workspace. */

const EMPTY_HOME = mkdtempSync(join(tmpdir(), "coder-skills-home-"));

/** No packaged skills either, so a test reads only what it made. */

const NO_BUILT_INS = mkdtempSync(join(tmpdir(), "coder-skills-builtin-"));

const SKILL = `---

name: house-style

description: How this repository writes prose.

describe("discovering skills", () => {

  it("reads the name, the description, and the body without its front matter", () => {

    const [skill] = discoverSkills(workspace({ "house-style": SKILL }), EMPTY_HOME);

    const [skill] = discoverSkills(workspace({ "house-style": SKILL }), EMPTY_HOME, NO_BUILT_INS);

    expect(skill).toMatchObject({

      name: "house-style",

  });

  it("takes the name from the front matter, not from the directory", () => {

    const [skill] = discoverSkills(workspace({ "some-folder": SKILL }), EMPTY_HOME);

    const [skill] = discoverSkills(workspace({ "some-folder": SKILL }), EMPTY_HOME, NO_BUILT_INS);

    expect(skill?.name).toBe("house-style");

  });

    const root = workspace({ "house-style": SKILL });

    mkdirSync(join(root, ".agents", "skills", "empty"), { recursive: true });

    expect(discoverSkills(root, EMPTY_HOME).map((skill) => skill.name)).toEqual(["house-style"]);

    expect(discoverSkills(root, EMPTY_HOME, NO_BUILT_INS).map((skill) => skill.name)).toEqual(["house-style"]);

  });

  it("skips a skill missing a name or a description", () => {

    });

    // One cannot be asked for and the other gives nothing to choose on.

    expect(discoverSkills(root, EMPTY_HOME).map((skill) => skill.name)).toEqual(["house-style"]);

    expect(discoverSkills(root, EMPTY_HOME, NO_BUILT_INS).map((skill) => skill.name)).toEqual(["house-style"]);

  });

    });

    // Taking `>-` as the value is how a skill came to describe itself as ">-".

    expect(discoverSkills(root, EMPTY_HOME)[0]?.description).toBe(

    expect(discoverSkills(root, EMPTY_HOME, NO_BUILT_INS)[0]?.description).toBe(

      "Use when the reader wants one sentence spread over two lines.",

    );

  });

      ),

    });

    expect(discoverSkills(root, EMPTY_HOME)[0]?.description).toBe("One.\nTwo.");

    expect(discoverSkills(root, EMPTY_HOME, NO_BUILT_INS)[0]?.description).toBe("One.\nTwo.");

  });

  it("is empty for a repository with no skills directory", () => {

    expect(discoverSkills(mkdtempSync(join(tmpdir(), "coder-skills-")), EMPTY_HOME)).toEqual([]);

    expect(discoverSkills(mkdtempSync(join(tmpdir(), "coder-skills-")), EMPTY_HOME, NO_BUILT_INS)).toEqual([]);

  });

  it("strips the quotes from a quoted description", () => {

      quoted: '---\nname: quoted\ndescription: "Quoted, with a comma."\n---\n\nBody.',

    });

    expect(discoverSkills(root, EMPTY_HOME)[0]?.description).toBe("Quoted, with a comma.");

    expect(discoverSkills(root, EMPTY_HOME, NO_BUILT_INS)[0]?.description).toBe("Quoted, with a comma.");

  });

});

describe("the skill tool", () => {

  const skills = discoverSkills(workspace({ "house-style": SKILL }), EMPTY_HOME);

  const skills = discoverSkills(workspace({ "house-style": SKILL }), EMPTY_HOME, NO_BUILT_INS);

  const tool = skillTool(skills);

  it("carries the catalog in its description, so both lanes read it", () => {

  };

  it("offers every skill until one is switched off", () => {

    const selection = loadSkillSelection(workspace(two), home());

    const selection = loadSkillSelection(workspace(two), home(), NO_BUILT_INS);

    expect(selection.active().map((skill) => skill.name)).toEqual(["alpha", "beta"]);

    expect(selection.isOn("alpha")).toBe(true);

  });

  it("drops a switched-off skill from what the model is offered", () => {

    const selection = loadSkillSelection(workspace(two), home());

    const selection = loadSkillSelection(workspace(two), home(), NO_BUILT_INS);

    selection.toggle("alpha");

    const root = workspace(two);

    const where = home();

    loadSkillSelection(root, where).toggle("beta");

    loadSkillSelection(root, where, NO_BUILT_INS).toggle("beta");

    expect(loadSkillSelection(root, where).active().map((skill) => skill.name)).toEqual(["alpha"]);

    expect(loadSkillSelection(root, where, NO_BUILT_INS).active().map((skill) => skill.name)).toEqual(["alpha"]);

  });

  it("switches one back on", () => {

    const root = workspace(two);

    const where = home();

    loadSkillSelection(root, where).toggle("beta");

    loadSkillSelection(root, where).toggle("beta");

    loadSkillSelection(root, where, NO_BUILT_INS).toggle("beta");

    loadSkillSelection(root, where, NO_BUILT_INS).toggle("beta");

    expect(loadSkillSelection(root, where).active().map((skill) => skill.name)).toEqual([

    expect(loadSkillSelection(root, where, NO_BUILT_INS).active().map((skill) => skill.name)).toEqual([

      "alpha",

      "beta",

    ]);

    const one = workspace(two);

    const other = workspace(two);

    loadSkillSelection(one, where).toggle("alpha");

    loadSkillSelection(one, where, NO_BUILT_INS).toggle("alpha");

    // A skill switched off for one repository is not switched off everywhere.

    expect(loadSkillSelection(other, where).active().map((skill) => skill.name)).toEqual([

    expect(loadSkillSelection(other, where, NO_BUILT_INS).active().map((skill) => skill.name)).toEqual([

      "alpha",

      "beta",

    ]);

  it("offers a skill added after the choice was made", () => {

    const root = workspace(two);

    const where = home();

    loadSkillSelection(root, where).toggle("alpha");

    loadSkillSelection(root, where, NO_BUILT_INS).toggle("alpha");

    mkdirSync(join(root, ".agents", "skills", "gamma"), { recursive: true });

    writeFileSync(

    );

    // Off is what is recorded, so something nobody has ruled on is on.

    expect(loadSkillSelection(root, where).active().map((skill) => skill.name)).toEqual([

    expect(loadSkillSelection(root, where, NO_BUILT_INS).active().map((skill) => skill.name)).toEqual([

      "beta",

      "gamma",

    ]);

  });

});

describe("the skills the CLI ships with", () => {

  it("offers its own, so a session knows the CLI it is part of", () => {

    const found = discoverSkills(mkdtempSync(join(tmpdir(), "coder-skills-")), EMPTY_HOME);

    expect(found.map((skill) => skill.name)).toContain("openagents-cli");

  });

  it("lets a repository replace one by name, with nothing to uninstall", () => {

    const root = workspace({

      "openagents-cli": "---\nname: openagents-cli\ndescription: Ours.\n---\n\nOur version.",

    });

    const found = discoverSkills(root, EMPTY_HOME);

    const ours = found.find((skill) => skill.name === "openagents-cli");

    // Nearest wins, and the packaged one is furthest.

    expect(ours?.description).toBe("Ours.");

    expect(found.filter((skill) => skill.name === "openagents-cli")).toHaveLength(1);

  });

  it("says what works with no credential, which help output does not", () => {

    const found = discoverSkills(mkdtempSync(join(tmpdir(), "coder-skills-")), EMPTY_HOME);

    const cli = found.find((skill) => skill.name === "openagents-cli");

    // The auth boundary is the part a model cannot discover by asking --help.

    expect(cli?.body).toContain("What works with no credential");

    expect(cli?.body).toContain("chat:account");

    expect(cli?.body).toContain("forge:write");

    expect(cli?.body).toContain("auth login --headless");

  });

});

import { describe, expect, it } from "vitest";

import { openagentsTool } from "../src/coder-tools.js";

const run = (args: ReadonlyArray<string>) =>

  openagentsTool().run({ args: [...args] }, new AbortController().signal);

describe("the openagents tool", () => {

  it("carries the catalog of what it is for, and points at --help", () => {

    const { description, parameters } = openagentsTool();

    expect(description).toContain("--help");

    expect(description).toContain("--json");

    expect(parameters["required"]).toEqual(["args"]);

  });

  it("runs the CLI this session is part of", async () => {

    // Resolved beside this module rather than from PATH, so what answers is

    // this build and not whichever copy happens to be installed.

    await expect(run(["--version"])).resolves.toContain("openagents v");

  });

  it("asks for arguments rather than running something arbitrary", async () => {

    await expect(run([])).resolves.toContain("`args` is required");

  });

  it("reports a failing command by its exit code, not as an empty answer", async () => {

    const output = await run(["issue", "view", "999999", "-R", "OpenAgentsInc/openagents"]);

    // An empty failure reads as an empty success.

    expect(output).toContain("exited with code");

  });

  it("refuses to start another coder session, and says what to use instead", async () => {

    const output = await run(["coder"]);

    expect(output).toContain("needs a terminal");

    expect(output).toContain("`delegate` tool");

  });

  it("refuses a login that would wait, and names the headless form", async () => {

    await expect(run(["auth", "login"])).resolves.toContain("auth login --headless");

  });

  it("allows the headless login, which is the one that does not wait", async () => {

    // The refusal is about waiting for a terminal, not about the command.

    const output = await run(["auth", "login", "--headless", "--help"]);

    expect(output).not.toContain("needs a terminal");

  });

  it("refuses a command that serves until it is stopped", async () => {

    await expect(run(["computer", "up"])).resolves.toContain("needs a terminal");

  });

});