@launchchair/agent 0.4.0 → 0.4.2

package/AGENTS.md

@@ -28,7 +28,7 @@ Fresh LaunchChair projects often do not have a local repo yet. Before Stack Setu
 
 ## Bridge And Runner Files
 
-Download these into a stable local folder such as `~/launchchair-agent` or `~/.hermes/launchchair-mcp`:
+Download these into a stable local folder such as `~/launchchair-agent`:
 
 ```bash
 mkdir -p "$HOME/launchchair-agent"
@@ -57,28 +57,37 @@ fi
 
 The final block creates a tiny project-local `AGENTS.md` pointer only when the target folder does not already have one. It helps fresh Codex chats auto-load the LaunchChair instructions without overwriting a real project instruction file.
 
-## Optional CLI
+## CLI
 
-MCP-only setup is still supported. Use `mcp-bridge-server.mjs` when the desktop agent exposes LaunchChair MCP tools. Use `launchchair-cli.mjs` when you need quick diagnostics, project discovery, retry-safe project creation, MCP config output, or a simple way to start the local bridge.
+The npm CLI is the recommended setup path for Codex Desktop and Claude Desktop. It can log in through LaunchChair, save the token locally, print paste-ready MCP config, write Claude Desktop config, and start the local bridge.
 
 ```bash
-node "$HOME/launchchair-agent/launchchair-cli.mjs" doctor
-node "$HOME/launchchair-agent/launchchair-cli.mjs" login
-node "$HOME/launchchair-agent/launchchair-cli.mjs" projects --query LeafLore
-node "$HOME/launchchair-agent/launchchair-cli.mjs" create --name SignalLift --one-liner "Distribution workspace for technical founders" --project-type b2b --idempotency-key signallift-v1
-node "$HOME/launchchair-agent/launchchair-cli.mjs" run-once
-node "$HOME/launchchair-agent/launchchair-cli.mjs" bridge
-node "$HOME/launchchair-agent/launchchair-cli.mjs" mcp-config codex
+npm install -g @launchchair/agent
+launchchair login
+launchchair setup codex --cwd /absolute/path/to/repo-or-empty-folder --write-config
+launchchair setup claude --cwd /absolute/path/to/repo-or-empty-folder --write-config
+launchchair projects --query LeafLore
+launchchair create --name SignalLift --one-liner "Distribution workspace for technical founders" --project-type b2b --idempotency-key signallift-v1
+launchchair run-once
+launchchair bridge
+launchchair mcp-config codex --ui-fields
 ```
 
-## Required Environment Variables
+If Codex Desktop is being configured through the custom MCP form instead of `~/.codex/config.toml`, run:
+
+```bash
+launchchair setup codex --cwd /absolute/path/to/repo-or-empty-folder --copy-config
+```
+
+## Environment Variables
 
 ```bash
 LAUNCHCHAIR_BASE_URL="https://www.launchchair.io"
-LAUNCHCHAIR_AGENT_TOKEN="<full lc_at token from LaunchChair Settings API Access>"
 LAUNCHCHAIR_PROJECT_ID="optional project UUID; omit or leave blank if creating or discovering a project"
 ```
 
+`launchchair login` is the recommended token path. It saves the token to `~/.launchchair/config.json`, and `launchchair mcp-server` reads that saved token. Use `LAUNCHCHAIR_AGENT_TOKEN` only as a manual fallback when browser login is skipped or a per-client token override is needed.
+
 For Codex Desktop local runs:
 
 ```bash
@@ -101,18 +110,26 @@ The build folder can be an empty scratch folder until Stack Setup creates or rec
 
 ```toml
 [mcp_servers.launchchair]
-command = "node"
-args = ["/Users/you/launchchair-agent/mcp-bridge-server.mjs"]
+command = "launchchair"
+args = ["mcp-server"]
+required = true
+startup_timeout_sec = 20
+tool_timeout_sec = 3600
+default_tools_approval_mode = "approve"
 
 [mcp_servers.launchchair.env]
 LAUNCHCHAIR_BASE_URL = "https://www.launchchair.io"
-LAUNCHCHAIR_AGENT_TOKEN = "<full lc_at token from Settings API Access>"
 LAUNCHCHAIR_PROJECT_ID = ""
 LC_AGENT_ROUTER_GPT_TARGET = "codex"
 LC_AGENT_ROUTER_CODEX_TARGET = "codex"
 LC_AGENT_CODEX_CWD = "/absolute/path/to/the-folder-codex-should-build-into"
+
+# Optional fallback if launchchair login was skipped:
+# LAUNCHCHAIR_AGENT_TOKEN = "<full lc_at token from Settings API Access>"
 ```
 
+If the desktop app cannot find `launchchair`, run `which launchchair` in Terminal and use that absolute path as the MCP command.
+
 ## What To Do First In A Fresh Chat
 
 1. If LaunchChair MCP tools are available, call `launchchair_heartbeat`.
@@ -229,7 +246,7 @@ Call launchchair_run_once.
 Run one queued UI job from CLI:
 
 ```bash
-node "$HOME/launchchair-agent/launchchair-cli.mjs" run-once
+launchchair run-once
 ```
 
 Select a generated wedge:

package/README.md

@@ -49,18 +49,24 @@ Tokens are masked in CLI output. Do not paste real tokens into public docs, scre
 
 ## Guided Setup
 
-Use `setup` as the easiest path. It saves the build folder, writes a small `AGENTS.md` pointer into that folder, starts browser login when no token is saved yet, prints the MCP config for your desktop agent, and tells you exactly what to do next.
+Use `setup` as the easiest path. It saves the build folder, writes a small `AGENTS.md` pointer into that folder, starts browser login when no token is saved yet, writes or prints the MCP config for your desktop agent, and tells you exactly what to do next.
 
 Codex Desktop:
 
 ```bash
-launchchair setup codex --cwd /absolute/path/to/repo-or-empty-folder
+launchchair setup codex --cwd /absolute/path/to/repo-or-empty-folder --write-config
+```
+
+If you prefer Codex Desktop's custom MCP form, copy paste-ready fields instead:
+
+```bash
+launchchair setup codex --cwd /absolute/path/to/repo-or-empty-folder --copy-config
 ```
 
 Claude Desktop + Claude Code:
 
 ```bash
-launchchair setup claude --cwd /absolute/path/to/repo-or-empty-folder
+launchchair setup claude --cwd /absolute/path/to/repo-or-empty-folder --write-config
 ```
 
 Terminal / CLI agents:
@@ -83,8 +89,8 @@ Use `setup terminal` when the agent runs inside a normal shell instead of Codex
 ## Common Commands
 
 ```bash
-launchchair setup codex --cwd /absolute/path/to/repo-or-empty-folder
-launchchair setup claude --cwd /absolute/path/to/repo-or-empty-folder
+launchchair setup codex --cwd /absolute/path/to/repo-or-empty-folder --write-config
+launchchair setup claude --cwd /absolute/path/to/repo-or-empty-folder --write-config
 launchchair setup terminal --cwd /absolute/path/to/repo-or-empty-folder
 launchchair projects
 launchchair projects --query LeafLore
@@ -94,6 +100,7 @@ launchchair continue --completion-target "rerun Product Ideation until ICP Pain
 launchchair run-once
 launchchair bridge
 launchchair mcp-config codex
+launchchair mcp-config codex --ui-fields --copy-config
 launchchair mcp-config claude
 launchchair install-agent-md --cwd /absolute/path/to/repo-or-empty-folder
 ```
@@ -127,6 +134,7 @@ Print a Codex MCP config example:
 
 ```bash
 launchchair mcp-config codex
+launchchair mcp-config codex --ui-fields
 ```
 
 Print a Claude Desktop MCP config example:
@@ -135,9 +143,9 @@ Print a Claude Desktop MCP config example:
 launchchair mcp-config claude
 ```
 
-The printed config intentionally uses a token placeholder. Paste your real `lc_at_` token into your MCP client config when the desktop client launches MCP directly, or use `launchchair login` for CLI-started bridge sessions.
+The recommended config launches `launchchair mcp-server`. That process reads the token saved by `launchchair login`, so Codex and Claude users do not need to paste tokens into MCP config after browser login.
 
-Desktop MCP clients do not automatically inherit the token saved by `launchchair login` unless they launch through a CLI-managed bridge process. For direct MCP config, put the token in that client config's `env` block.
+Use `LAUNCHCHAIR_AGENT_TOKEN` only as a manual fallback when you skip `launchchair login`, need a per-client token override, or your desktop app cannot read the saved CLI config. If a desktop app cannot find `launchchair`, run `which launchchair` and use that absolute path as the MCP command.
 
 ## Local Bridge
 

package/launchchair-cli.mjs

@@ -8,14 +8,14 @@
  * project discovery/creation, and local bridge control.
  */
 
-import { spawn } from "node:child_process";
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 
-const VERSION = "0.4.0";
+const VERSION = "0.4.2";
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_BASE_URL = "https://www.launchchair.io";
 const CONFIG_DIR = process.env.LAUNCHCHAIR_CONFIG_DIR?.trim()
@@ -163,11 +163,13 @@ Commands:
   continue [--project-id ID]       Ask LaunchChair to continue the project loop once
   run-once                        Claim and run one queued LaunchChair job through the local bridge
   bridge                          Start the long-running local bridge for Run with Agent
+  mcp-server                      Run the stdio MCP server using saved CLI config
   setup codex|claude|terminal [options]
                                   Guided setup for CLI, CWD, AGENTS.md, MCP config, and bridge
   config                          Show local CLI config without printing the token
   config set KEY VALUE             Save base-url, project-id, codex-cwd, or claude-code-cwd
-  mcp-config codex|claude         Print MCP config with current paths/defaults
+  mcp-config codex|claude [options]
+                                  Print MCP config or Codex custom MCP form fields
   install-agent-md [--cwd PATH]   Create a small AGENTS.md pointer in a fresh repo
 
 Create options:
@@ -207,6 +209,9 @@ Setup options:
   --no-open                       During setup login, print the approval URL instead of opening a browser
   --timeout SECONDS               During setup login, approval timeout. Default: 600
   --start-bridge                  Start the local bridge after setup
+  --copy-config                   Copy generated MCP setup output to clipboard on macOS
+  --ui-fields                     Print Codex custom MCP form fields instead of raw config
+  --write-config                  Write/update Codex or Claude Desktop MCP config when supported
 
 Login options:
   --token TOKEN                   Manual fallback: save an existing lc_at token
@@ -223,6 +228,10 @@ Env:
   LC_AGENT_CODEX_CWD              Folder Codex should build into
   LC_AGENT_CLAUDE_CODE_CWD        Folder Claude Code should build into
 
+MCP config options:
+  --ui-fields                     Print fields for Codex Desktop's custom MCP form
+  --copy-config                   Copy generated output to clipboard on macOS
+
 Config:
   ${CONFIG_PATH}
 `);
@@ -731,51 +740,185 @@ function spawnBridge(extraArgs = []) {
   });
 }
 
-function renderMcpConfig(target) {
+function spawnMcpServer(extraArgs = []) {
   const bridgePath = path.join(SCRIPT_DIR, "mcp-bridge-server.mjs");
-  const agentTokenPlaceholder = "<full lc_at token from LaunchChair Settings API Access>";
-  const projectId = defaultProjectId() || "optional-if-agent-creates-project";
-  if (target === "claude") {
+  const child = spawn(process.execPath, [bridgePath, ...extraArgs], {
+    stdio: "inherit",
+    env: buildBridgeEnv(),
+  });
+  child.on("exit", (code) => {
+    process.exit(code ?? 0);
+  });
+}
+
+function normalizedMcpTarget(target) {
+  return targetDetails(target || "codex").mcpTarget || "codex";
+}
+
+function tomlString(value) {
+  return JSON.stringify(String(value ?? ""));
+}
+
+function mcpEnvForTarget(target, options = {}) {
+  const includeTokenPlaceholder = options.includeTokenPlaceholder !== false;
+  const details = targetDetails(target || "codex");
+  const projectId = defaultProjectId();
+  const cwd = configValue(details.cwdConfigKey, [details.cwdEnvName], "/absolute/path/to/repo-or-empty-folder");
+  const envBlock = {
+    LAUNCHCHAIR_BASE_URL: baseUrl(),
+    ...(token() || !includeTokenPlaceholder ? {} : { LAUNCHCHAIR_AGENT_TOKEN: "<optional full lc_at token when launchchair login was not used>" }),
+    ...(projectId ? { LAUNCHCHAIR_PROJECT_ID: projectId } : {}),
+    LC_AGENT_ROUTER_GPT_TARGET: details.routerTarget,
+    LC_AGENT_ROUTER_CODEX_TARGET: details.routerTarget,
+    [details.cwdEnvName]: cwd,
+  };
+  return Object.fromEntries(Object.entries(envBlock).filter(([, value]) => String(value ?? "").trim()));
+}
+
+function mcpServerConfig(target, options = {}) {
+  return {
+    command: "launchchair",
+    args: ["mcp-server"],
+    env: mcpEnvForTarget(target, options),
+  };
+}
+
+function renderMcpConfig(target, options = {}) {
+  const normalized = normalizedMcpTarget(target);
+  const server = mcpServerConfig(normalized, options);
+  if (normalized === "claude") {
     return JSON.stringify(
       {
         mcpServers: {
-          launchchair: {
-            command: "node",
-            args: [bridgePath],
-            env: {
-              LAUNCHCHAIR_BASE_URL: baseUrl(),
-              LAUNCHCHAIR_AGENT_TOKEN: agentTokenPlaceholder,
-              LAUNCHCHAIR_PROJECT_ID: projectId,
-              LC_AGENT_ROUTER_GPT_TARGET: "claude_code",
-              LC_AGENT_ROUTER_CODEX_TARGET: "claude_code",
-              LC_AGENT_CLAUDE_CODE_CWD: configValue("claudeCodeCwd", ["LC_AGENT_CLAUDE_CODE_CWD"], "/absolute/path/to/repo-or-empty-folder"),
-            },
-          },
+          launchchair: server,
         },
       },
       null,
       2,
     );
   }
+  const envLines = Object.entries(server.env)
+    .map(([key, value]) => `${key} = ${tomlString(value)}`)
+    .join("\n");
   return `[mcp_servers.launchchair]
-command = "node"
-args = ["${bridgePath}"]
-required = true
+command = "launchchair"
+args = ["mcp-server"]
+required = false
 startup_timeout_sec = 20
 tool_timeout_sec = 3600
 default_tools_approval_mode = "approve"
 
 [mcp_servers.launchchair.env]
-LAUNCHCHAIR_BASE_URL = "${baseUrl()}"
-LAUNCHCHAIR_AGENT_TOKEN = "${agentTokenPlaceholder}"
-LAUNCHCHAIR_PROJECT_ID = "${projectId}"
-LC_AGENT_ROUTER_GPT_TARGET = "codex"
-LC_AGENT_ROUTER_CODEX_TARGET = "codex"
-LC_AGENT_CODEX_CWD = "${configValue("codexCwd", ["LC_AGENT_CODEX_CWD"], "/absolute/path/to/repo-or-empty-folder")}"`;
+${envLines}`;
+}
+
+function renderMcpUiFields(target) {
+  const normalized = normalizedMcpTarget(target);
+  const details = targetDetails(normalized);
+  const server = mcpServerConfig(normalized);
+  const envLines =
+    Object.entries(server.env)
+      .map(([key, value]) => `  ${key} = ${value}`)
+      .join("\n") || "  (none)";
+  const workingDir = server.env[details.cwdEnvName] || process.cwd();
+  return `Name
+  launchchair
+
+Type
+  STDIO
+
+Command to launch
+  ${server.command}
+
+Arguments
+  ${server.args.join(" ")}
+
+Environment variables
+${envLines}
+
+Working directory
+  ${workingDir}`;
+}
+
+function copyToClipboard(text) {
+  if (process.platform !== "darwin") return false;
+  const result = spawnSync("pbcopy", { input: text, encoding: "utf8" });
+  return result.status === 0;
+}
+
+function claudeDesktopConfigPath() {
+  return path.join(os.homedir() || process.cwd(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+}
+
+function codexConfigPath() {
+  return path.join(os.homedir() || process.cwd(), ".codex", "config.toml");
 }
 
-function printMcpConfig(target) {
-  print(renderMcpConfig(target));
+function removeCodexLaunchChairTables(raw) {
+  const lines = String(raw || "").split(/\r?\n/);
+  const kept = [];
+  let skipping = false;
+
+  for (const line of lines) {
+    const tableName = line.match(/^\s*\[([^\]]+)\]\s*$/)?.[1] ?? "";
+    if (tableName) {
+      if (tableName === "mcp_servers.launchchair" || tableName === "mcp_servers.launchchair.env") {
+        skipping = true;
+        continue;
+      }
+      skipping = false;
+    }
+    if (!skipping) kept.push(line);
+  }
+
+  return kept.join("\n").replace(/\n{3,}$/g, "\n\n").trimEnd();
+}
+
+function writeCodexConfig() {
+  const configPath = codexConfigPath();
+  mkdirSync(path.dirname(configPath), { recursive: true });
+  let current = "";
+  if (existsSync(configPath)) {
+    current = readFileSync(configPath, "utf8");
+    const backupPath = `${configPath}.launchchair-backup-${Date.now()}`;
+    copyFileSync(configPath, backupPath);
+    ok(`Backed up existing Codex config to ${backupPath}`);
+  }
+  const preserved = removeCodexLaunchChairTables(current);
+  const next = `${preserved ? `${preserved}\n\n` : ""}${renderMcpConfig("codex", { includeTokenPlaceholder: false })}\n`;
+  writeFileSync(configPath, next);
+  return configPath;
+}
+
+function writeClaudeDesktopConfig() {
+  const configPath = claudeDesktopConfigPath();
+  mkdirSync(path.dirname(configPath), { recursive: true });
+  let current = {};
+  if (existsSync(configPath)) {
+    const raw = readFileSync(configPath, "utf8");
+    current = raw.trim() ? JSON.parse(raw) : {};
+    const backupPath = `${configPath}.launchchair-backup-${Date.now()}`;
+    copyFileSync(configPath, backupPath);
+    ok(`Backed up existing Claude config to ${backupPath}`);
+  }
+  const next = {
+    ...current,
+    mcpServers: {
+      ...(current.mcpServers ?? {}),
+      launchchair: mcpServerConfig("claude", { includeTokenPlaceholder: false }),
+    },
+  };
+  writeFileSync(configPath, `${JSON.stringify(next, null, 2)}\n`);
+  return configPath;
+}
+
+function printMcpConfig(target, args = {}) {
+  const output = args["ui-fields"] === true || args["print-ui-fields"] === true ? renderMcpUiFields(target) : renderMcpConfig(target);
+  print(output);
+  if (args["copy-config"] === true) {
+    if (copyToClipboard(output)) ok("Copied MCP setup output to clipboard.");
+    else warn("Could not copy MCP setup output automatically on this platform.");
+  }
 }
 
 function showConfig() {
@@ -947,8 +1090,23 @@ async function setup(args) {
     print(`  ${paint("launchchair run-once", "cyan")}`);
     print(`  ${paint("launchchair bridge", "cyan")}`);
   } else {
-    title("MCP config to paste");
-    print(renderMcpConfig(details.mcpTarget));
+    if (details.mcpTarget === "codex" && args["write-config"] === true) {
+      const configPath = writeCodexConfig();
+      title("Codex MCP config updated");
+      ok(`Wrote LaunchChair MCP server to ${configPath}`);
+    } else if (details.mcpTarget === "claude" && args["write-config"] === true) {
+      const configPath = writeClaudeDesktopConfig();
+      title("Claude MCP config updated");
+      ok(`Wrote LaunchChair MCP server to ${configPath}`);
+    } else {
+      const output = details.mcpTarget === "codex" || args["ui-fields"] === true ? renderMcpUiFields(details.mcpTarget) : renderMcpConfig(details.mcpTarget);
+      title(details.mcpTarget === "codex" || args["ui-fields"] === true ? "MCP fields to paste" : "MCP config to paste");
+      print(output);
+      if (args["copy-config"] === true) {
+        if (copyToClipboard(output)) ok("Copied MCP setup output to clipboard.");
+        else warn("Could not copy MCP setup output automatically on this platform.");
+      }
+    }
   }
 
   print("");
@@ -964,11 +1122,23 @@ async function setup(args) {
     print("3. For product/project work, have it use launchchair projects/create/continue before local code discovery.");
     print("4. Keep launchchair bridge running only when LaunchChair UI Run with agent jobs should be picked up.");
   } else {
-    print(`1. Paste the MCP config above into ${details.label}.`);
-    print(`2. Restart or reload ${details.label} so the MCP server is exposed to fresh chats.`);
-    print("3. Keep this bridge running when you want LaunchChair's Run with agent button to work:");
+    if (details.mcpTarget === "codex" && args["write-config"] === true) {
+      print("1. Restart or reload Codex Desktop so the MCP server is exposed to fresh chats.");
+      print("2. Keep the generated config file under your user profile; it launches the saved LaunchChair CLI token.");
+    } else if (details.mcpTarget === "codex") {
+      print("1. Fill the Codex custom MCP form with the fields above.");
+      print("2. Restart or reload Codex Desktop so the MCP server is exposed to fresh chats.");
+    } else if (details.mcpTarget === "claude" && args["write-config"] === true) {
+      print("1. Restart or reload Claude Desktop so the MCP server is exposed to fresh chats.");
+      print("2. Keep the generated config file under your user profile; it launches the saved LaunchChair CLI token.");
+    } else {
+      print(`1. Paste the MCP config above into ${details.label}.`);
+      print(`2. Restart or reload ${details.label} so the MCP server is exposed to fresh chats.`);
+    }
+    print("3. If the desktop app cannot find launchchair, run `which launchchair` and use that absolute path as the command.");
+    print("4. Keep this bridge running when you want LaunchChair's Run with agent button to work:");
     print(`   ${paint("launchchair bridge", "cyan")}`);
-    print("4. Start a fresh agent chat. Codex will discover the LaunchChair skill and MCP server instructions automatically.");
+    print("5. Start a fresh agent chat. The agent should discover the LaunchChair skill and MCP server instructions automatically.");
   }
   print("");
   row("Build folder", cwd, "cyan");
@@ -999,10 +1169,11 @@ async function main() {
   if (command === "continue") return continueProject(args);
   if (command === "run-once") return spawnBridge(["--once", "--verbose"]);
   if (command === "bridge") return spawnBridge(["--verbose"]);
+  if (command === "mcp-server") return spawnMcpServer();
   if (command === "setup") return setup(args);
   if (command === "config" && args._[0] === "set") return setConfig({ ...args, _: args._.slice(1) });
   if (command === "config") return showConfig();
-  if (command === "mcp-config") return printMcpConfig(args._[0] || "codex");
+  if (command === "mcp-config") return printMcpConfig(args._[0] || "codex", args);
   if (command === "install-agent-md") return installAgentMd(args);
   throw new Error(`Unknown command: ${command}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@launchchair/agent",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "LaunchChair Agent CLI, MCP bridge, local bridge, and runners for Codex, Claude Code, ChatGPT, Claude, and Hermes workflows.",
   "type": "module",
   "bin": {