@ashulab/agent-forge 0.2.0 → 0.4.0

package/README.md

@@ -9,7 +9,7 @@ On each run the launcher:
 - detects installed provider CLIs on your PATH
 - asks which provider to use (or takes it from a flag)
 - starts the provider with the GitHub token and a per-agent git identity injected into the environment
-- writes the agent's `systemPrompt` into the provider's startup memory file (`CLAUDE.md` / `AGENTS.md`) so subagents inherit the identity
+- injects the agent's `systemPrompt` per process (`claude --append-system-prompt`, `codex -c developer_instructions`; antigravity falls back to an `AGENTS.md` block)
 
 Provider auth stays in the provider CLI — the launcher never handles provider API keys.
 
@@ -60,9 +60,10 @@ The shape, for reference — the `"$schema"` line points at the published schema
 }
 ```
 
-- The **installation id is not stored** — it is resolved on each run, in order: the owner of the repo you launch in, then `account`, then the App's sole installation. So the same agent works across every org the App is installed on, and it survives an uninstall/reinstall (which rotates the id).
-- Add `"account": "<org-or-user login>"` only when you run outside a matching repo and the App has more than one installation.
-- `installationId` is still accepted as an explicit override — set it to pin a specific id or skip the lookup (offline, or in a git credential helper).
+- The **installation id is not stored** — it is resolved on each run, in order: the owner of the repo you launch in, then the App's sole installation. So the same agent works across every org the App is installed on, and it survives an uninstall/reinstall (which rotates the id).
+- An App installed on more than one account only resolves when you launch from inside a repo it covers — that repo picks the installation.
+- `installationId` is accepted as an explicit override — set it to pin a specific id or skip the lookup (offline, or in a git credential helper).
+- One agent, many accounts: a **private** GitHub App only installs on the account that owns it. To run the agent on both a personal account and an org, make the App public or use one App per account — see [docs/github-app.md](docs/github-app.md).
 - `botId` is optional. When omitted it is resolved from the GitHub API using `botName` so the git author email links commits to the bot. Set it explicitly only to skip that lookup (e.g. offline).
 - Do not put provider-specific config here — providers are auto-detected from PATH.
 
@@ -87,23 +88,25 @@ By default the installation token carries the full installation scope. Narrow it
 
 Omitting the `permissions` key entirely is the safe default — the token then carries whatever the App grants. `repositories` works the same way: list it and the token can only touch those repos.
 
-On launch, `agent-forge` prints the scope GitHub actually granted (`token` row in the summary); `agent-forge token --agent <name>` prints it to stderr. If a call fails with `403 Resource not accessible by integration`, check that row first.
+On launch, `agent-forge` prints the scope GitHub actually granted (`scope` row in the summary, alongside the `account` the token is for); `agent-forge token --agent <name>` prints it to stderr. If a call fails with `403 Resource not accessible by integration`, check that row first.
 
 ## Add an agent
 
 You need a GitHub App first — its **App ID**, a **private key**, and an **installation**. If you don't have one yet, follow [docs/github-app.md](docs/github-app.md).
 
+Running `agent-forge` with no agents configured offers to run the wizard for you.
+
 ### Guided (recommended)
 
 ```bash
 agent-forge add
 ```
 
-You provide the **GitHub App ID** and the **path to its private key**. The wizard derives the rest from the GitHub API — slug (`botName`), bot user id, and the account (asked only when the App is installed on more than one) — asks for a label and an optional system prompt, mints a test token to confirm it works, and writes the entry. It writes to the resolved config path — the global registry (`~/.config/agent-forge/agents.json`) unless `$AGENT_FORGE_CONFIG` or an existing `./agents.json` redirects it.
+You provide the **GitHub App ID** and the **path to its private key**. The wizard derives the rest from the GitHub API — slug (`botName`), bot user id — asks for a label and an optional system prompt, mints a test token to confirm it works, and writes the entry. It writes to the resolved config path — the global registry (`~/.config/agent-forge/agents.json`) unless `$AGENT_FORGE_CONFIG` or an existing `./agents.json` redirects it.
 
 ### Manual
 
-Copy one agent object inside the `agents` array and set unique values for `name`, `label`, `appId`, `botName`, `privateKeyPath` — plus `account` if the App has more than one installation. Make sure the private key file exists and is readable.
+Copy one agent object inside the `agents` array and set unique values for `name`, `label`, `appId`, `botName`, `privateKeyPath`. Make sure the private key file exists and is readable.
 
 ## Launch
 
@@ -113,26 +116,41 @@ Interactive:
 agent-forge
 ```
 
-Direct flags (passing both skips all prompts; passing one pre-fills it):
+Direct flags (passing both skips the menus; passing one pre-fills it, the other is prompted — or auto-picked when only one agent or provider is available):
 
 ```bash
 agent-forge --agent ops-agent --provider claude
 agent-forge --agent review-agent --provider codex
 ```
 
+Before launching, it prints a summary:
+
+```
+│  provider  claude
+│  identity  ops-agent[bot]
+│  account   AshuLab            ← which account the token is for
+│  repo      AshuLab/app        ← the repo you're in (drives account)
+│  scope     write: contents, issues, pull_requests  ·  +4 read
+│  expires   ~59m               ← installation tokens last ~1h
+```
+
+(The `antigravity` provider adds a `memory` row pointing at the `AGENTS.md` it wrote.)
+
 Other commands:
 
 ```bash
 agent-forge --list
+agent-forge --version
 agent-forge --help
 ```
 
 ### Provider-specific prompt behavior
 
-- `claude`: passed via `--append-system-prompt` (lands in the real system prompt)
-- `codex` / `antigravity` (`agy`): no CLI flag — identity comes from `AGENTS.md` only (`agy --prompt` is headless `--print`; a codex positional arg is a fake first user turn)
+`systemPrompt` is injected per process — no repo file is touched:
 
-The launcher also writes `systemPrompt` into the provider's startup memory file in the working directory (`CLAUDE.md` for claude, `AGENTS.md` for codex and antigravity), inside a managed `agent-forge:identity` block. This keeps the identity in place for subagents the provider spawns, not just its main thread. The block is rewritten on each run and safe to keep in version control.
+- `claude`: `--append-system-prompt` (lands in the real system prompt)
+- `codex`: `-c developer_instructions=…` (appends a developer message; unlike `model_instructions_file` it does not replace codex's base prompt)
+- `antigravity` (`agy`): no such flag — the launcher writes `systemPrompt` into `AGENTS.md` in the working directory, inside a managed `agent-forge:identity` block. Do not commit it. Run one agent per worktree.
 
 ## Token refresh
 

package/dist/launcher.cjs

@@ -4017,7 +4017,7 @@ var require_jsonwebtoken = __commonJS({
 // src/launcher.js
 var import_node_child_process3 = require("node:child_process");
 var import_node_path4 = require("node:path");
-var import_node_util3 = require("node:util");
+var import_node_util4 = require("node:util");
 
 // node_modules/.pnpm/@clack+core@1.4.3/node_modules/@clack/core/dist/index.mjs
 var import_node_util = require("node:util");
@@ -5377,19 +5377,9 @@ function pickInstallation(installations, agent) {
   if (installations.length === 0) {
     throw new Error(`GitHub App ${agent.appId} has no installations. Install it on an account or org first.`);
   }
-  if (agent.account) {
-    const want = String(agent.account).toLowerCase();
-    const match = installations.find((item) => item.account.toLowerCase() === want);
-    if (!match) {
-      throw new Error(
-        `GitHub App ${agent.appId} is not installed on "${agent.account}". Installed on: ${installations.map((item) => item.account).join(", ")}.`
-      );
-    }
-    return match.id;
-  }
   if (installations.length === 1) return installations[0].id;
   throw new Error(
-    `GitHub App ${agent.appId} is installed on ${installations.length} accounts (${installations.map((item) => item.account).join(", ")}). Run inside a repo under one of them, or add "account" to agent "${agent.name}".`
+    `GitHub App ${agent.appId} is installed on ${installations.length} accounts (${installations.map((item) => item.account).join(", ")}). Launch from inside a repo under one of them.`
   );
 }
 function parseGithubRemote(url) {
@@ -5409,19 +5399,21 @@ function currentRepoSlug() {
 async function installationForRepo(slug, jwtToken) {
   try {
     const data = await githubApi(`/repos/${slug.owner}/${slug.repo}/installation`, { jwtToken });
-    return String(data.id);
+    return { id: String(data.id), account: data.account?.login || data.account?.slug || null };
   } catch {
     return null;
   }
 }
-async function resolveInstallationId(agent, jwtToken) {
-  if (agent.installationId) return String(agent.installationId);
+async function resolveInstallation(agent, jwtToken) {
+  if (agent.installationId) return { id: String(agent.installationId), account: null };
   const slug = currentRepoSlug();
   if (slug) {
-    const id = await installationForRepo(slug, jwtToken);
-    if (id) return id;
+    const hit = await installationForRepo(slug, jwtToken);
+    if (hit) return hit;
   }
-  return pickInstallation(await listInstallations(jwtToken), agent);
+  const installations = await listInstallations(jwtToken);
+  const id = pickInstallation(installations, agent);
+  return { id, account: installations.find((item) => item.id === id)?.account ?? null };
 }
 function buildTokenScope(agent) {
   const scope = {};
@@ -5432,13 +5424,15 @@ function buildTokenScope(agent) {
 async function generateGithubAppToken(agent) {
   const privateKey = readPrivateKey(agent.privateKeyPath, agent.name || agent.appId);
   const jwtToken = signAppJwt(agent.appId, privateKey);
-  const installationId = await resolveInstallationId(agent, jwtToken);
+  const { id: installationId, account } = await resolveInstallation(agent, jwtToken);
   const data = await githubApi(`/app/installations/${installationId}/access_tokens`, {
     jwtToken,
     body: buildTokenScope(agent)
   });
   return {
     token: data.token,
+    account,
+    expiresAt: data.expires_at || null,
     // What GitHub actually granted, after both the App's config and our scoping.
     permissions: data.permissions || {},
     repositorySelection: data.repository_selection || "all"
@@ -5480,7 +5474,9 @@ function getProviderPromptArgs(providerName, agent) {
   if (!prompt) {
     return [];
   }
-  return providerName === "claude" ? ["--append-system-prompt", prompt] : [];
+  if (providerName === "claude") return ["--append-system-prompt", prompt];
+  if (providerName === "codex") return ["-c", `developer_instructions=${JSON.stringify(prompt)}`];
+  return [];
 }
 
 // src/identity.js
@@ -5488,7 +5484,7 @@ var import_node_fs3 = require("node:fs");
 var import_node_path3 = require("node:path");
 var START = "<!-- agent-forge:identity:start -->";
 var END = "<!-- agent-forge:identity:end -->";
-var MEMORY_FILE = { claude: "CLAUDE.md", codex: "AGENTS.md", antigravity: "AGENTS.md" };
+var MEMORY_FILE = { antigravity: "AGENTS.md" };
 function upsertIdentityBlock(content, prompt) {
   const block2 = `${START}
 ${prompt}
@@ -5515,10 +5511,97 @@ function syncIdentityFile(providerName, agent, cwd = process.cwd()) {
   return file;
 }
 
+// src/format.js
+function formatScope(permissions, full = false) {
+  const entries = Object.entries(permissions);
+  if (entries.length === 0) return "full installation scope";
+  if (full) return entries.map(([name, level]) => `${name}:${level}`).join(" ");
+  const writes = entries.filter(([, level]) => level !== "read").map(([name]) => name);
+  if (writes.length === 0) return `read-only (${entries.length})`;
+  const reads = entries.length - writes.length;
+  return `write: ${writes.join(", ")}${reads ? `  \xB7  +${reads} read` : ""}`;
+}
+function formatExpiry(iso) {
+  const ms = new Date(iso).getTime() - Date.now();
+  if (!Number.isFinite(ms)) return String(iso);
+  const minutes = Math.round(ms / 6e4);
+  return minutes > 0 ? `~${minutes}m` : "expired";
+}
+
+// src/cli.js
+var import_node_util3 = require("node:util");
+
+// package.json
+var package_default = {
+  name: "@ashulab/agent-forge",
+  version: "0.4.0",
+  description: "Give claude/codex/antigravity their own GitHub identity: a bot account, a scoped token minted per run, git attribution to match",
+  license: "MIT",
+  author: "Diego Ghersi <ghersidl@gmail.com>",
+  type: "module",
+  bin: {
+    "agent-forge": "dist/launcher.cjs"
+  },
+  main: "dist/launcher.cjs",
+  files: [
+    "dist",
+    "schema",
+    "LICENSE",
+    "README.md"
+  ],
+  engines: {
+    node: ">=24"
+  },
+  packageManager: "pnpm@11.20.0",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/AshuLab/agent-forge.git"
+  },
+  bugs: {
+    url: "https://github.com/AshuLab/agent-forge/issues"
+  },
+  homepage: "https://github.com/AshuLab/agent-forge#readme",
+  keywords: [
+    "github-app",
+    "cli",
+    "coding-agent",
+    "claude",
+    "codex",
+    "antigravity",
+    "installation-token",
+    "git-identity"
+  ],
+  publishConfig: {
+    access: "public"
+  },
+  scripts: {
+    dev: "node src/launcher.js",
+    test: "node --test",
+    start: "node dist/launcher.cjs",
+    build: "esbuild src/launcher.js --bundle --platform=node --format=cjs --target=node24 --outfile=dist/launcher.cjs --banner:js='#!/usr/bin/env node' && chmod +x dist/launcher.cjs",
+    prepublishOnly: "pnpm build && pnpm test"
+  },
+  dependencies: {
+    "@clack/prompts": "^1.7.0",
+    jsonwebtoken: "^9.0.3"
+  },
+  devDependencies: {
+    esbuild: "^0.28.2"
+  }
+};
+
 // src/cli.js
+var LOGO = `
+\u2584\u2584  \u2584\u2584\u2584 \u2584\u2584\u2584 \u2584\u2584  \u2584\u2584\u2584      \u2584\u2584\u2584 \u2584\u2584  \u2584\u2584  \u2584\u2584\u2584 \u2584\u2584\u2584
+\u2588\u2584\u2588 \u2588 \u2584 \u2588\u2584  \u2588 \u2588  \u2588       \u2588\u2584  \u2588 \u2588 \u2588\u2584\u2580 \u2588 \u2584 \u2588\u2584
+\u2588 \u2588 \u2580\u2584\u2588 \u2588\u2584\u2584 \u2588 \u2588  \u2588       \u2588   \u2580\u2584\u2580 \u2588 \u2588 \u2580\u2584\u2588 \u2588\u2584\u2584
+`;
+function printVersion() {
+  console.log(package_default.version);
+}
 function printHelp() {
   console.log(`
-Agent Forge
+Agent Forge v${package_default.version}
 
 Usage:
   agent-forge
@@ -5526,6 +5609,7 @@ Usage:
   agent-forge add                    guided setup for a new agent
   agent-forge token --agent <name>   print a fresh GitHub App token (for refresh)
   agent-forge --list
+  agent-forge --version
   agent-forge --help
 
 Requirements:
@@ -5539,10 +5623,13 @@ Config resolution (first match wins):
   - ./agents.json                          (only if it already exists)
 `);
 }
+function bail(message = "Cancelled") {
+  cancel(`\u2716  ${message}`);
+  process.exit(0);
+}
 function keep(value) {
   if (isCancel(value)) {
-    cancel("Cancelled.");
-    process.exit(0);
+    bail();
   }
   return value;
 }
@@ -5569,17 +5656,8 @@ async function addAgentWizard({ embedded = false } = {}) {
   if (meta.installations.length === 0) {
     throw new Error("This App has no installations. Install it on an account or org first.");
   }
-  let account;
-  if (meta.installations.length === 1) {
-    note(`${meta.installations[0].account} \u2014 resolved automatically each run`, "Installation");
-  } else {
-    account = keep(
-      await select({
-        message: "Which account is this agent for?",
-        options: meta.installations.map((i2) => ({ value: i2.account, label: `${i2.account} (${i2.id})` }))
-      })
-    );
-  }
+  const where = meta.installations.length === 1 ? `${meta.installations[0].account} \u2014 resolved automatically each run` : `${meta.installations.map((i2) => i2.account).join(", ")} \u2014 resolved from the repo you launch in`;
+  note(where, "Installation");
   const name = (keep(await text({ message: "Agent name", placeholder: meta.slug, defaultValue: meta.slug })) || meta.slug).trim();
   const label = (keep(await text({ message: "Label", placeholder: meta.name, defaultValue: meta.name })) || meta.name).trim();
   const systemPrompt = keep(await text({ message: "System prompt (optional)", placeholder: "You are ..." })).trim();
@@ -5589,7 +5667,6 @@ async function addAgentWizard({ embedded = false } = {}) {
     appId,
     botName: meta.slug,
     privateKeyPath,
-    ...account ? { account } : {},
     ...systemPrompt ? { systemPrompt } : {}
   };
   const check = spinner();
@@ -5614,7 +5691,7 @@ async function interactiveSelection(defaults = {}) {
   if (agents.length === 0 && !defaults.agent) {
     note("No agents configured yet. Each agent is a GitHub App identity the launcher runs under.", "First run");
     if (!keep(await confirm({ message: "Add one now?" }))) {
-      cancel(`Run "agent-forge add" when you're ready.`);
+      outro(`Run ${(0, import_node_util3.styleText)("cyan", "agent-forge add")} when you're ready.`);
       process.exit(0);
     }
     await addAgentWizard({ embedded: true });
@@ -5644,9 +5721,9 @@ async function interactiveSelection(defaults = {}) {
       })
     );
   }
-  if (!keep(await confirm({ message: `Launch ${agentChoice} with ${providerChoice}?` }))) {
-    cancel("Cancelled.");
-    process.exit(0);
+  const launchPrompt = `Launch ${(0, import_node_util3.styleText)("green", agentChoice)} with ${(0, import_node_util3.styleText)(["cyan", "bold"], providerChoice)}?`;
+  if (!keep(await confirm({ message: launchPrompt }))) {
+    bail("Cancelled \u2014 nothing launched");
   }
   return { agentName: agentChoice, providerName: providerChoice };
 }
@@ -5655,6 +5732,7 @@ function parseArgs() {
   const result = {
     command: args[0] && !args[0].startsWith("-") ? args[0] : void 0,
     help: false,
+    version: false,
     list: false,
     agent: void 0,
     provider: void 0
@@ -5664,6 +5742,7 @@ function parseArgs() {
     const arg = args[i2];
     const next = args[i2 + 1];
     if (arg === "--help" || arg === "-h") result.help = true;
+    if (arg === "--version" || arg === "-v") result.version = true;
     if (arg === "--list" || arg === "-l") result.list = true;
     if (arg === "--agent" || arg === "-a") {
       result.agent = value(next);
@@ -5677,7 +5756,8 @@ function parseArgs() {
   return result;
 }
 function showIntro() {
-  intro("Agent Forge");
+  console.log((0, import_node_util3.styleText)("cyan", LOGO));
+  intro(`Agent Forge ${(0, import_node_util3.styleText)("dim", `v${package_default.version}`)}`);
 }
 
 // src/launcher.js
@@ -5703,10 +5783,10 @@ async function launchAgent(agentName, providerName) {
   const providerInfo = getProviderInfo(providerName, agent);
   const s = spinner();
   s.start("Minting installation token");
-  const { token: githubToken, permissions, repositorySelection } = await generateGithubAppToken(agent);
+  const { token: githubToken, account, expiresAt, permissions, repositorySelection } = await generateGithubAppToken(agent);
   const botId = await resolveBotId(agent);
   const gitIdentity = buildGitIdentity(agent, botId);
-  s.stop(`Token ready for ${(0, import_node_util3.styleText)("green", gitIdentity.GIT_AUTHOR_NAME)}`);
+  s.stop(`Token ready for ${(0, import_node_util4.styleText)("green", gitIdentity.GIT_AUTHOR_NAME)}`);
   const identityFile = syncIdentityFile(providerName, agent);
   const runtimeEnv = {
     ...process.env,
@@ -5714,18 +5794,24 @@ async function launchAgent(agentName, providerName) {
     GH_TOKEN: githubToken,
     ...gitIdentity
   };
-  const scopeEntries = Object.entries(permissions);
-  const scopeText = scopeEntries.length ? scopeEntries.map(([name, level]) => `${name}:${level}`).join(" ") : "full installation scope";
-  const row = (label, value) => `${(0, import_node_util3.styleText)("dim", label.padEnd(10))}${value}`;
+  const narrowed = Boolean(agent.permissions) || Boolean(agent.repositories);
+  const scopeText = formatScope(permissions, narrowed);
+  const repoSlug = currentRepoSlug();
+  const row = (label, value) => `${(0, import_node_util4.styleText)("dim", label.padEnd(10))}${value}`;
   const summary = [
-    row("provider", (0, import_node_util3.styleText)(["cyan", "bold"], providerName)),
-    row("identity", (0, import_node_util3.styleText)("green", gitIdentity.GIT_AUTHOR_NAME)),
-    row("token", (0, import_node_util3.styleText)("dim", repositorySelection === "selected" ? `${scopeText} \xB7 selected repos` : scopeText))
+    row("provider", (0, import_node_util4.styleText)(["cyan", "bold"], providerName)),
+    row("identity", (0, import_node_util4.styleText)("green", gitIdentity.GIT_AUTHOR_NAME))
   ];
+  if (account) summary.push(row("account", (0, import_node_util4.styleText)("yellow", account)));
+  if (repoSlug) summary.push(row("repo", (0, import_node_util4.styleText)("dim", `${repoSlug.owner}/${repoSlug.repo}`)));
+  summary.push(
+    row("scope", (0, import_node_util4.styleText)("dim", repositorySelection === "selected" ? `${scopeText}  \xB7  selected repos` : scopeText))
+  );
+  if (expiresAt) summary.push(row("expires", (0, import_node_util4.styleText)("dim", formatExpiry(expiresAt))));
   if (identityFile) {
-    summary.push(row("memory", (0, import_node_util3.styleText)("dim", (0, import_node_path4.relative)(process.cwd(), identityFile) || identityFile)));
+    summary.push(row("memory", (0, import_node_util4.styleText)("dim", (0, import_node_path4.relative)(process.cwd(), identityFile) || identityFile)));
   }
-  note(summary.join("\n"), (0, import_node_util3.styleText)("bold", agent.label || agent.name));
+  note(summary.join("\n"), (0, import_node_util4.styleText)("bold", agent.label || agent.name));
   const providerArgs = getProviderPromptArgs(providerName, agent);
   const child = (0, import_node_child_process3.spawn)(providerInfo.command, providerArgs, {
     stdio: "inherit",
@@ -5739,7 +5825,7 @@ async function launchAgent(agentName, providerName) {
     cancel(`Could not execute ${providerInfo.command}: ${error.message}`);
     process.exit(1);
   });
-  outro(`Running ${(0, import_node_util3.styleText)("cyan", providerName)}\u2026`);
+  outro(`Running ${(0, import_node_util4.styleText)("cyan", providerName)}\u2026`);
 }
 async function main() {
   const flags = parseArgs();
@@ -5747,6 +5833,10 @@ async function main() {
     printHelp();
     return;
   }
+  if (flags.version) {
+    printVersion();
+    return;
+  }
   if (flags.list) {
     listAgents();
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashulab/agent-forge",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Give claude/codex/antigravity their own GitHub identity: a bot account, a scoped token minted per run, git attribution to match",
   "license": "MIT",
   "author": "Diego Ghersi <ghersidl@gmail.com>",

package/schema/agents.schema.json

@@ -25,13 +25,9 @@
             "type": "string",
             "description": "GitHub App ID (numeric, stored as a string)"
           },
-          "account": {
-            "type": "string",
-            "description": "Account/org login where the App is installed. Fallback for installation-id resolution when you run outside a matching repo. Needed only when the App has more than one installation. Resolution order: repo owner, then account, then the sole installation."
-          },
           "installationId": {
             "type": "string",
-            "description": "Optional override. Normally the installation id is resolved (repo owner, then account, then the sole installation). Set this to pin a specific id or skip the lookup (offline, or in a git credential helper)."
+            "description": "Optional override. Normally the installation id is resolved (repo owner, then the App's sole installation). Set this to pin a specific id or skip the lookup (offline, or in a git credential helper)."
           },
           "botName": {
             "type": "string",