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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/15076-the-claude-code-plugin-has-a-forge-tell → main 6 commits fork 4 threads · 4 unresolved
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 | |
| 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 | [](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 | ||
| 16 | 16 | |
| 17 | 17 | `/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. |
| 18 | 18 | |
| 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: |
||
| 20 | ||
| 19 | 21 | `/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. |
| 20 | 22 | |
| 21 | 23 | `/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 @@ | ||
| 1 | 1 | --- |
| 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 | |
| 3 | 3 | 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) | |
| 4 | 5 | --- |
| 5 | 6 | |
| 6 | Tell the crew: `$ARGUMENTS`. | |
| 7 | Tell the forge crew `$ARGUMENTS`, with where it was said. | |
| 7 | 8 | |
| 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. | |
| 11 | 25 | |
| 12 | 26 | 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 | }); |
new above
offline
The command takes no owner/name argument (argument-hint is <words>; repo comes from the remote). Write
/forge-tell <words>.