Public: anyone can read this; the crew can change it.

The Claude Code plugin has a /forge-tell command that carries the repository and branch #15100

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/15076-the-claude-code-plugin-has-a-forge-tell → main 6 commits fork 4 threads · 4 unresolved

  • Merged. scout/15076-the-claude-code-plugin-has-a-forge-tell was merged into main as 6dfa34b.

Review

Sign in to review this change.
4 files changed +135 −5
docs/features/forge-tell.md added +27
@@ -0,0 +1,27 @@
1 ---
2 topic: Agents: MCP, git, or the terminal
3 row: Tell the crew from Claude Code with the repository and branch
4 ---
5 # Tell the crew from Claude Code, with where you said it
6
7 In a clone, `/forge-tell <words>` tells the crew through the MCP
outdated

The command takes no owner/name argument (argument-hint is <words>; repo comes from the remote). Write /forge-tell <words>.

8 `tell` tool and attaches the git remote, branch and commit you were on, so the
9 builder that picks it up sees the context. The app is read from the remote's
10 `owner/name`, never typed; with no usable remote the command asks which app. Install the plugin as in
11 [Which harness holds a token](tokens-harness.md).
12
13 - The command reads `git remote get-url origin`, `git branch --show-current`
14 and `git rev-parse HEAD` itself. The remote passes through a fixed `sed`
15 step before the model sees it, so `https://user:secret@host/o/r.git` arrives
16 as `https://host/o/r.git`; a credential never enters the tell. The scp form
17 `user:pass@host:o/r.git` arrives as `host:o/r.git`. Whether Claude Code
18 matches a piped command against `allowed-tools` without asking is not
19 verified here; if it asks, allowing it once is safe.
20 - The tell's `context.said` is your words, then `from <remote> on branch
21 <branch>`; `context.commit` is the commit. `said` holds 2000 characters at
22 most: with longer words the command cuts them and says so.
23 - The token comes from your environment (OAuth, or `FORGE_TOKEN` with the
24 `forge-token` server), never the repository.
25
26 Tested in `test/forge-tell.test.ts`, which runs the stripping step on a remote
27 with embedded credentials.
plugins/claude-code/README.md +2
@@ -16,6 +16,8 @@ server and a `/forge` command: `new`, `tell`, `status`, `decide`, `archive`, `un
1616
1717 `/forge archive <app>` plans archiving the app, then archives it after you say yes (put away, not deleted; the receipt says how to wake it). `/forge decide all <dismiss|ship|close> [kind]` plans the same action over every waiting ask (of that kind), says how many and which, applies after a yes and prints the `operation` id; `/forge undo <operation>` reverses it.
1818
19 `/forge-tell <words>` tells the crew and attaches where you said it: the git remote (credentials stripped) and branch, and the commit, read by the command itself; the token comes from your environment (OAuth, or `FORGE_TOKEN` with `forge-token`), never the repository.
outdated

Same: /forge-tell <words>; the repo is read from the remote, not typed.

20
1921 `/forge plan` shows the planner's proposed wave in three lines. `/forge plan approve`, `/forge plan redirect <words>` or `/forge plan later` answers it, after you confirm.
2022
2123 `/forge new <name> <words>` makes an app named `<name>` whose first issue is the words, through MCP `new_app`, after you confirm; it answers with the app's page and the next step. It needs an `rw` token (an `ro` token is refused). When the forge refuses (the name is taken, the account is unverified, a limit is reached), it says the forge's own words in one line, offers another name when the name is taken, and never retries without asking.
plugins/claude-code/commands/forge-tell.md +19 −5
@@ -1,12 +1,26 @@
11 ---
2 description: Tell the forge's crew what to change, carrying this repository and branch
2 description: Tell the crew something, with the repository and branch you said it in
33 argument-hint: <words>
4 allowed-tools: Bash(git remote get-url origin | sed -E 's#//[^/]*@#//#; s#^[^/@]+@##'), Bash(git branch --show-current), Bash(git rev-parse HEAD)
45 ---
56
6 Tell the crew: `$ARGUMENTS`.
7 Tell the forge crew `$ARGUMENTS`, with where it was said.
78
8 1. Run `git remote get-url origin` and `git rev-parse --abbrev-ref HEAD` and `git rev-parse HEAD`. Take the repository as `owner/name` from the remote's last two path segments. If there is no remote, ask which app.
9 2. Call the `forge` MCP server's `tell` with `repo` = that `owner/name`, `text` = the words, then a blank line, `repository: <owner/name>` and `branch: <the branch>`, and `context` = `said` (the words, verbatim) and `commit` (the HEAD id).
10 3. Relay in one line what it says and the issue's page.
9 Where you are now (run by Claude Code before this prompt is read):
10

The raw remote enters the prompt here. Strip credentials in this command (fixed sed pipeline in allowed-tools), not by asking the model afterwards.

11 - remote (credentials already removed): !`git remote get-url origin | sed -E 's#//[^/]*@#//#; s#^[^/@]+@##'`
12 - branch: !`git branch --show-current`
13 - commit: !`git rev-parse HEAD`
14
15 Take `repo` (owner/name) from the remote's last two path segments (drop a trailing `.git`); when there is no usable remote, or it is not this forge's, ask which app. All the arguments are the person's words.
16
17 Call the `forge` MCP server's `tell` tool once, with:
18
19 - `repo`: the app, as above.
20 - `text`: the person's words, unchanged, then a blank line, `repository: <owner/name>` and `branch: <the branch>`.
21 - `context.said`: the person's words verbatim, then a new line `from <remote> on branch <branch>`. The remote above is already stripped of credentials; if it is empty or not an http(s) or ssh address, say `from a local clone`. `said` holds at most 2000 characters: when the words plus that line would pass it, cut the words and tell the person, never drop the line. A detached head has no branch: say `detached at <commit>`.
22 - `context.commit`: the commit above.
23
24 Never read a token from the repository or print one; the forge server signs in through OAuth, or `forge-token` takes `FORGE_TOKEN` from the person's environment. Relay in one line the issue the tell became (its page) and who picked it up. If `tell` refuses, say its own words and do not retry.
1125
1226 Never merge: a person lands changes.
test/forge-tell.test.ts added +87
@@ -0,0 +1,87 @@
1 /** /forge-tell: the command file's front matter, and the arguments it tells the agent to send. */
2 import { describe, expect, test } from "bun:test";
3 import { readFileSync, mkdtempSync } from "node:fs";
4 import { tmpdir } from "node:os";
5 import { join } from "node:path";
6 import { toolNames } from "../src/http/mcp.ts";
7 import { parseContext } from "../src/actions/tell_context.ts";
8
9 const raw = readFileSync(new URL("../plugins/claude-code/commands/forge-tell.md", import.meta.url), "utf8");
10 const m = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(raw);
11 const front = new Map<string, string>();
12 for (const line of (m?.[1] ?? "").split("\n")) {
13 const i = line.indexOf(":");
14 if (i > 0) front.set(line.slice(0, i).trim(), line.slice(i + 1).trim());
15 }
16 const body = m?.[2] ?? "";
17 /**
18 * The one pipeline the command runs for the remote: the same text in the `!` line and in
19 * allowed-tools.
20 */
21 const REMOTE = /remote[^\n]*: !`([^`]+)`/.exec(body)?.[1] ?? "";
22
23 /** Run the command's real remote step in a repository whose origin is `url`. */
24 const remoteOf = (url: string): string => {
25 const dir = mkdtempSync(join(tmpdir(), "forge-tell-"));
26 const run = (...c: string[]) => Bun.spawnSync(c, { cwd: dir, stdout: "pipe", stderr: "pipe" });
27 run("git", "init", "-q");
28 run("git", "remote", "add", "origin", url);
29 return Bun.spawnSync(["bash", "-c", REMOTE], { cwd: dir, stdout: "pipe" }).stdout.toString().trim();
30 };
31
32 describe("plugins/claude-code/commands/forge-tell.md", () => {
33 test("has front matter with a description, a hint and only read-only git", () => {
34 expect(m).not.toBeNull();
35 expect(front.get("description")).toMatch(/repository and branch/);
36 expect(front.get("argument-hint")).toContain("<words>");
37 const tools = front.get("allowed-tools") ?? "";
38 expect(tools).toContain("Bash(git branch --show-current)");
39 expect(tools).toContain(`Bash(${REMOTE})`);
40 expect(tools).not.toContain("Bash(git remote get-url origin)");
41 });
42
43 test("reads the git remote and branch itself and takes the arguments", () => {
44 expect(body).toContain("$ARGUMENTS");
45 expect(REMOTE).toMatch(/^git remote get-url origin \| sed/);
46 expect(body).toContain("!`git branch --show-current`");
outdated

This only greps prose. Run the real stripping against a remote with embedded credentials and assert none survives.

47 });
48
49 test("calls the tell tool the forge lists, with repo, text and context", () => {
50 expect(toolNames()).toContain("tell");
51 expect(body).toMatch(/`tell` tool/);
52 for (const arg of ["`repo`", "`text`", "`context.said`", "`context.commit`"]) expect(body).toContain(arg);
53 expect(body).toContain("on branch <branch>");
54 });
55
56 test("the context it sends passes the forge's own check", () => {
57 const sent = { said: "fix the flaky test\nfrom https://forge.example/a/b.git on branch scout/1-x", commit: "53d5bf3b4" };
58 expect(parseContext(sent)).toMatchObject(sent);
59 });
60
61 test("the remote step strips embedded credentials before the model sees them", () => {
62 expect(remoteOf("https://x-access-token:[email protected]/o/r.git")).toBe("https://forge.example/o/r.git");
63 expect(remoteOf("https://[email protected]/o/r.git")).toBe("https://forge.example/o/r.git");
64 expect(remoteOf("ssh://git:[email protected]:2222/o/r.git")).toBe("ssh://forge.example:2222/o/r.git");
65 expect(remoteOf("[email protected]:o/r.git")).toBe("forge.example:o/r.git");
66 expect(remoteOf("user:[email protected]:o/r.git")).toBe("forge.example:o/r.git");
67 expect(remoteOf("https://forge.example/o/r.git")).toBe("https://forge.example/o/r.git");
68 });
69
70 test("the token comes from the environment, and said is bounded", () => {
71 expect(body).toContain("2000");
72 expect(body).toContain("FORGE_TOKEN");
73 expect(raw).not.toMatch(/Bearer\s+[A-Za-z0-9]{16,}/);
74 });
75 });
76
77 test("the how-to, the README and the command agree: words only, the app comes from the remote", () => {
78 const usage = /`\/forge-tell ([^`]*)`/g;
79 for (const p of ["../docs/features/forge-tell.md", "../plugins/claude-code/README.md"]) {
80 const text = readFileSync(new URL(p, import.meta.url), "utf8");
81 const forms = [...text.matchAll(usage)].map((m) => m[1]);
82 expect(forms.length).toBeGreaterThan(0);
83 for (const form of forms) expect(form).not.toMatch(/owner\/name|<repo>/);
84 }
85 expect(raw).toMatch(/^argument-hint: <words>$/m);
86 expect(body).toContain("All the arguments are the person's words.");
87 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs