overlord-cli 0.2605281741.0 → 0.2605290912.0

package/README.md

@@ -60,6 +60,8 @@ Common commands:
 ovld auth login
 ovld auth status
 ovld attach
+ovld claude "Refactor the auth middleware" --model opus --thinking high
+ovld codex "Investigate the memory leak" -- --search --full-auto
 ovld create "Investigate the failing build" --agent codex
 ovld prompt "Draft a fix for the onboarding flow"
 ovld version
@@ -85,6 +87,8 @@ ovld doctor
 
 For ticket-scoped protocol and launch commands, `ticket_id` values such as `1:899` carry the organization id. The CLI uses that first, then `--organization-id` for UUID compatibility, then stored auth. `ovld auth login` stores the first available organization as a default when an account belongs to multiple organizations; pass `--organization-id <id>` only when you want a different default.
 
+When `ovld launch` has an explicit `--working-directory`, or when you run it from a registered project directory containing `.overlord/project.json`, it exports `TMPDIR`, `TMP`, `TEMP`, and `OVERLORD_TMPDIR` to that project's `.overlord/tmp/` directory before spawning the agent. Otherwise it falls back to the system temp directory.
+
 ## Requirements
 
 - Node.js 20 or newer
@@ -96,6 +100,7 @@ Find full CLI docs here: https://www.ovld.ai/docs/surfaces/cli
 
 Top-level commands (see `ovld help`):
 
+- `<agent> "<prompt>"` - create a ticket from the prompt (project inferred from the current directory) and launch the agent on it in one step, e.g. `ovld claude "fix the flaky login test" --model opus`. Built-in agents need an installed connector (`ovld setup <agent>`, override with `--allow-uninstalled`); your custom agents launch by id. Flags after a standalone `--` pass through to the agent binary.
 - `attach` - search tickets and launch an agent interactively (`ovld attach [ticketId] [agent]`)
 - `create` - create a ticket with numbered project selection; supports `--agent`, `--model`, `--delegate` (same delegate flags as `ovld protocol create`)
 - `prompt` - create a ticket, then launch an agent on it

package/bin/_cli/direct-launch.mjs

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+
+/**
+ * Direct agent launch: `ovld <agent> "<prompt>" [overlord flags] [-- passthrough]`.
+ *
+ * Creates a ticket from the prompt (project inferred from the working directory),
+ * then launches the chosen agent on it — giving power users all of Overlord's
+ * tracking without ever opening the desktop/web UI. Launch is limited to agents
+ * with an installed connector (built-ins) or one of the user's custom agents.
+ *
+ * This is a thin composition over existing pieces:
+ *   - `/api/protocol/prompt` creates + auto-titles the ticket and resolves the
+ *     project from the working directory.
+ *   - `runLauncherCommand('run' | 'launch-custom', …)` launches the agent locally.
+ */
+
+import { buildAuthHeaders, resolveAuth } from './credentials.mjs';
+import {
+  BUILTIN_LAUNCH_AGENTS,
+  agentIdentifierMap,
+  runLauncherCommand
+} from './launcher.mjs';
+import { isAgentConnectorInstalled } from './setup.mjs';
+
+/** Overlord flags that take a value (everything else after `--key` is a boolean). */
+const VALUE_FLAGS = new Set([
+  'project-id',
+  'priority',
+  'title',
+  'acceptance-criteria',
+  'available-tools',
+  'working-directory',
+  'model',
+  'thinking',
+  'delegate',
+  'pre-command',
+  'launch-mode',
+  'organization-id',
+  'ssh-command',
+  'remote-working-directory',
+  'server-multiplexer',
+  'tmux-command'
+]);
+
+const BOOLEAN_FLAGS = new Set(['personal', 'for-human', 'allow-uninstalled']);
+
+/** Launch flags forwarded verbatim to `ovld launch`/`launch-custom`. */
+const FORWARDED_VALUE_FLAGS = [
+  'pre-command',
+  'launch-mode',
+  'organization-id',
+  'ssh-command',
+  'remote-working-directory',
+  'server-multiplexer',
+  'tmux-command'
+];
+
+export function isBuiltinLaunchAgent(name) {
+  return BUILTIN_LAUNCH_AGENTS.includes(String(name ?? '').trim().toLowerCase());
+}
+
+/**
+ * Substitute `{{token}}` placeholders in a custom-agent command template.
+ * Mirrors `resolveCustomAgentCommand` in lib/helpers/custom-agent.ts (kept in
+ * sync by hand because the published CLI cannot import the app's TypeScript).
+ */
+export function resolveTemplate(template, values) {
+  const substituted = String(template).replace(
+    /\{\{\s*([\w.-]+)\s*\}\}/g,
+    (_match, token) => {
+      const value = values[token];
+      return typeof value === 'string' ? value.trim() : '';
+    }
+  );
+  return substituted.replace(/\s+/g, ' ').trim();
+}
+
+/** Default placeholder values for a custom agent given a model/thinking choice. */
+export function buildCustomAgentValues(agent, model, thinking) {
+  const values = {};
+  for (const placeholder of agent.placeholders ?? []) {
+    if (placeholder.role === 'model' && model) {
+      values[placeholder.token] = model;
+    } else if (placeholder.role === 'thinking' && thinking) {
+      values[placeholder.token] = thinking;
+    } else if (Array.isArray(placeholder.options) && placeholder.options.length > 0) {
+      values[placeholder.token] = placeholder.options[0].value;
+    }
+  }
+  return values;
+}
+
+/**
+ * Parse direct-launch args into the objective, recognized Overlord flags, the
+ * repeatable `--flag` values, and everything after a standalone `--`.
+ */
+export function parseDirectLaunchArgs(rawArgs) {
+  const args = Array.isArray(rawArgs) ? rawArgs : [];
+  const sepIdx = args.indexOf('--');
+  const head = sepIdx === -1 ? args : args.slice(0, sepIdx);
+  const passthrough = sepIdx === -1 ? [] : args.slice(sepIdx + 1);
+
+  const flags = {};
+  const repeatedFlags = [];
+  const positionals = [];
+
+  for (let i = 0; i < head.length; i++) {
+    const arg = head[i];
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+
+    const eqIdx = arg.indexOf('=');
+    const key = eqIdx === -1 ? arg.slice(2) : arg.slice(2, eqIdx);
+    const inlineValue = eqIdx === -1 ? undefined : arg.slice(eqIdx + 1);
+
+    if (key === 'flag') {
+      const value = inlineValue !== undefined ? inlineValue : head[++i];
+      if (value !== undefined) repeatedFlags.push(value);
+      continue;
+    }
+
+    if (BOOLEAN_FLAGS.has(key)) {
+      flags[key] =
+        inlineValue === undefined ? true : /^(1|true|yes|)$/i.test(inlineValue);
+      continue;
+    }
+
+    if (inlineValue !== undefined) {
+      flags[key] = inlineValue;
+      continue;
+    }
+
+    // Value-taking flag (known or unknown): consume the next token unless it
+    // looks like another flag.
+    if (i + 1 < head.length && !head[i + 1].startsWith('--')) {
+      flags[key] = head[++i];
+    } else {
+      flags[key] = true;
+    }
+  }
+
+  return {
+    objective: positionals.join(' ').trim(),
+    flags,
+    repeatedFlags,
+    passthrough
+  };
+}
+
+function resolveForHuman(flags) {
+  const raw = flags['for-human'];
+  if (raw === undefined) return false;
+  if (raw === true) return true;
+  const normalized = String(raw).trim().toLowerCase();
+  return normalized === '' || normalized === 'true' || normalized === '1' || normalized === 'yes';
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function fetchUserAgents({ platformUrl, bearerToken, localSecret, organizationId }) {
+  const res = await fetch(`${platformUrl}/api/protocol/agents`, {
+    headers: buildAuthHeaders(bearerToken, localSecret, organizationId)
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(
+      `Failed to list agents (${res.status}): ${data.error ?? JSON.stringify(data)}`
+    );
+  }
+  return {
+    builtins: Array.isArray(data.builtins) ? data.builtins : [],
+    customAgents: Array.isArray(data.customAgents) ? data.customAgents : []
+  };
+}
+
+async function createPromptTicket(
+  { platformUrl, bearerToken, localSecret, organizationId },
+  body
+) {
+  const res = await fetch(`${platformUrl}/api/protocol/prompt`, {
+    method: 'POST',
+    headers: {
+      ...buildAuthHeaders(bearerToken, localSecret, organizationId),
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(body)
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const detail = data.error ?? JSON.stringify(data);
+    throw new Error(`Failed to create ticket (${res.status}): ${detail}`);
+  }
+  return data;
+}
+
+function printDirectLaunchHelp(agent = '<agent>') {
+  console.log(`Usage:
+  ovld ${agent} "<prompt>" [overlord flags] [-- <agent passthrough flags>]
+
+Creates a ticket from the prompt (project inferred from the current directory),
+then launches the agent on it and runs the normal ticket lifecycle.
+
+Overlord flags:
+  --model <identifier>          Preferred model (sets the ticket delegate and is forwarded to the agent)
+  --thinking <level>            Agent reasoning/effort level
+  --flag <value>                Extra agent flag (repeatable)
+  --pre-command <command>       Command to run before the agent binary (e.g. ollama)
+  --project-id <uuid>           Target project (skips working-directory resolution)
+  --personal                    Create the ticket in your personal project
+  --for-human                   Create a human-review ticket
+  --priority <low|medium|high|urgent>
+  --title "<title>"             Override the auto-generated title
+  --working-directory <path>    Directory used for project resolution and launch
+  --allow-uninstalled           Launch a built-in agent even if its connector isn't installed
+  --launch-mode <run|ask>       Ask mode adjusts the fetched prompt context
+  --ssh-command / --remote-working-directory / --server-multiplexer / --tmux-command
+
+Agent passthrough:
+  Anything after a standalone \`--\` is forwarded verbatim to the agent binary.
+
+Examples:
+  ovld claude "refactor the auth middleware" --model opus --thinking high
+  ovld codex "investigate the memory leak" -- --search --full-auto
+  ovld cursor "tidy the dashboard styles" --project-id <uuid> --for-human
+  echo "summarize today's diffs" | ovld claude`);
+}
+
+/**
+ * Entry point for `ovld <agent> …`. `agent` is argv[0]; `rawArgs` is the rest.
+ */
+export async function runDirectLaunch(agent, rawArgs = []) {
+  if (rawArgs[0] === '--help' || rawArgs[0] === '-h' || rawArgs[0] === 'help') {
+    printDirectLaunchHelp(agent);
+    return;
+  }
+
+  const normalizedAgent = String(agent ?? '').trim().toLowerCase();
+  const { objective: parsedObjective, flags, repeatedFlags, passthrough } =
+    parseDirectLaunchArgs(rawArgs);
+
+  let objective = parsedObjective;
+  if (!objective && !process.stdin.isTTY) {
+    objective = (await readStdin()).trim();
+  }
+
+  const builtin = isBuiltinLaunchAgent(normalizedAgent);
+  const auth = await resolveAuth();
+
+  // Classify + gate the agent before we create a ticket.
+  let customAgent = null;
+  if (builtin) {
+    if (!flags['allow-uninstalled'] && !isAgentConnectorInstalled(normalizedAgent)) {
+      console.error(
+        `The ${normalizedAgent} connector is not installed. Run \`ovld setup ${normalizedAgent}\` first, ` +
+          `or pass --allow-uninstalled to launch anyway.`
+      );
+      process.exit(1);
+    }
+  } else {
+    const { customAgents } = await fetchUserAgents(auth);
+    customAgent =
+      customAgents.find(candidate => candidate.id === agent) ??
+      customAgents.find(candidate => candidate.id === normalizedAgent) ??
+      customAgents.find(candidate => candidate.name === agent) ??
+      null;
+    if (!customAgent) {
+      console.error(`Unknown agent: "${agent}".`);
+      console.error(`Built-in agents: ${BUILTIN_LAUNCH_AGENTS.join(', ')}`);
+      console.error(
+        customAgents.length
+          ? `Your custom agents: ${customAgents.map(a => a.id).join(', ')}`
+          : 'You have no custom agents. Create one in Overlord settings to launch it by id.'
+      );
+      process.exit(1);
+    }
+  }
+
+  if (!objective) {
+    console.error('An objective is required. Provide it as a quoted argument or pipe it via stdin.');
+    printDirectLaunchHelp(agent);
+    process.exit(1);
+  }
+
+  const personal = Boolean(flags.personal);
+  const explicitProject =
+    typeof flags['project-id'] === 'string' && flags['project-id'].trim().length > 0;
+  const explicitWorkingDirectory =
+    typeof flags['working-directory'] === 'string' && flags['working-directory'].trim().length > 0
+      ? flags['working-directory'].trim()
+      : '';
+  // Send cwd so the server can resolve the project, unless the caller pinned a
+  // project or asked for a personal ticket.
+  const workingDirectory =
+    explicitWorkingDirectory || (!explicitProject && !personal ? process.cwd() : '');
+
+  const model = typeof flags.model === 'string' ? flags.model.trim() : '';
+  const thinking = typeof flags.thinking === 'string' ? flags.thinking.trim() : '';
+  const agentIdentifier = builtin ? agentIdentifierMap[normalizedAgent] : 'custom';
+  const delegate =
+    (typeof flags.delegate === 'string' && flags.delegate.trim()) || model || agentIdentifier;
+
+  const body = {
+    objectives: [{ objective }],
+    agentIdentifier,
+    connectionMethod: 'cli',
+    metadata: { launchedVia: 'ovld-direct', ...(model ? { model } : {}) },
+    delegate,
+    ...(flags.title ? { title: String(flags.title) } : {}),
+    ...(flags.priority ? { priority: String(flags.priority) } : {}),
+    ...(explicitProject ? { projectId: String(flags['project-id']).trim() } : {}),
+    ...(personal ? { personal: true } : {}),
+    ...(workingDirectory ? { workingDirectory } : {}),
+    ...(flags['acceptance-criteria']
+      ? { acceptanceCriteria: String(flags['acceptance-criteria']) }
+      : {}),
+    ...(flags['available-tools'] ? { availableTools: String(flags['available-tools']) } : {}),
+    ...(resolveForHuman(flags) ? { forHuman: true } : {})
+  };
+
+  const result = await createPromptTicket(auth, body);
+  const ticketId = result.ticket?.ticket_id ?? result.ticket?.id;
+  if (!ticketId) {
+    console.error('Ticket creation did not return a ticket id.');
+    process.exit(1);
+  }
+
+  console.log(`Created ticket ${ticketId} — launching ${agent}…`);
+  process.env.TICKET_ID = String(ticketId);
+
+  const baseLaunchArgs = ['--ticket-id', String(ticketId)];
+  if (workingDirectory) baseLaunchArgs.push('--working-directory', workingDirectory);
+  for (const name of FORWARDED_VALUE_FLAGS) {
+    const value = flags[name];
+    if (typeof value === 'string' && value.trim()) {
+      baseLaunchArgs.push(`--${name}`, value.trim());
+    }
+  }
+
+  if (builtin) {
+    const launchArgs = [normalizedAgent, ...baseLaunchArgs];
+    if (model) launchArgs.push('--model', model);
+    if (thinking) launchArgs.push('--thinking', thinking);
+    for (const flag of repeatedFlags) launchArgs.push('--flag', flag);
+    // Forward `--` passthrough as individual agent flags (same channel as --flag).
+    for (const token of passthrough) launchArgs.push('--flag', token);
+    await runLauncherCommand('run', launchArgs);
+    return;
+  }
+
+  // Custom agent: resolve the template locally, then append any --flag/passthrough
+  // tokens to the resolved command (launch-custom runs `<command> <context>`).
+  const values = buildCustomAgentValues(customAgent, model, thinking);
+  const extraTokens = [...repeatedFlags, ...passthrough].filter(Boolean);
+  const resolvedCommand = [resolveTemplate(customAgent.commandTemplate, values), ...extraTokens]
+    .join(' ')
+    .trim();
+  await runLauncherCommand('launch-custom', ['--command', resolvedCommand, ...baseLaunchArgs]);
+}

package/bin/_cli/index.mjs

@@ -29,6 +29,7 @@ function printHelp(primaryCommand) {
 Primary command: ${primaryCommand}
 
 Usage:
+  ${primaryCommand} <agent> "<prompt>" [flags]  Create a ticket from the prompt and launch the agent on it
   ${primaryCommand} attach [ticketId] [agent]  Search tickets and launch an agent (interactive)
   ${primaryCommand} create "<objective>"       Create a ticket with numbered project selection; supports --agent/--model/--delegate
   ${primaryCommand} prompt "<objective>"       Create a ticket, then launch an agent on it
@@ -48,6 +49,10 @@ Usage:
   ${primaryCommand} help                       Show this help message
 
 Agents:
+  ${primaryCommand} <agent> "<prompt>" [--model <id>] [--thinking <level>] [-- <agent flags>]
+    Built-in agents (claude, codex, cursor, antigravity, opencode) must have an
+    installed connector (${primaryCommand} setup <agent>); your custom agents launch by id.
+    Anything after a standalone -- is forwarded verbatim to the agent binary.
   Use ${primaryCommand} protocol help for ticket lifecycle commands.
   Key protocol commands: auth-status, discover-project, create, prompt, attach, connect, load-context.
 
@@ -172,12 +177,23 @@ export async function runCli({ primaryCommand }) {
     command === 'connect' ||
     command === 'restart' ||
     command === 'run' ||
-    command === 'resume'
+    command === 'resume' ||
+    command === 'launch-custom'
   ) {
     await runLauncherCommand(command, rest);
     return;
   }
 
+  // Direct agent launch: `ovld <agent> "<prompt>" [flags]`. Built-in agents
+  // dispatch immediately; an unknown command with a candidate objective may be
+  // a user's custom agent, so we let direct-launch resolve and report it.
+  const { isBuiltinLaunchAgent, runDirectLaunch } = await import('./direct-launch.mjs');
+  const hasCandidateObjective = rest.some(arg => !arg.startsWith('--'));
+  if (isBuiltinLaunchAgent(command) || hasCandidateObjective) {
+    await runDirectLaunch(command, rest);
+    return;
+  }
+
   console.error(`Unknown command: ${command}\n`);
   printHelp(primaryCommand);
   process.exit(1);

package/bin/_cli/launcher.mjs

@@ -17,6 +17,29 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_CLAUDE_PLUGIN_DIR = path.resolve(__dirname, '..', '..', 'plugins', 'claude');
 const REPO_CLAUDE_PLUGIN_DIR = path.resolve(__dirname, '..', '..', '..', '..', 'plugins', 'claude');
 
+function resolveLaunchScratchDir(workingDirectory, { explicit = false } = {}) {
+  const trimmed = typeof workingDirectory === 'string' ? workingDirectory.trim() : '';
+  const candidate = trimmed || process.cwd();
+  const useProjectScratch =
+    explicit || fs.existsSync(path.join(candidate, '.overlord', 'project.json'));
+  if (!useProjectScratch) {
+    return os.tmpdir();
+  }
+  const scratchDir = path.join(candidate, '.overlord', 'tmp');
+  fs.mkdirSync(scratchDir, { recursive: true });
+  return scratchDir;
+}
+
+function withLaunchTempEnv(baseEnv, scratchDir) {
+  return {
+    ...baseEnv,
+    TMPDIR: scratchDir,
+    TMP: scratchDir,
+    TEMP: scratchDir,
+    OVERLORD_TMPDIR: scratchDir
+  };
+}
+
 function claudeSourcePluginDir() {
   if (fs.existsSync(PACKAGE_CLAUDE_PLUGIN_DIR)) return PACKAGE_CLAUDE_PLUGIN_DIR;
   if (fs.existsSync(REPO_CLAUDE_PLUGIN_DIR)) return REPO_CLAUDE_PLUGIN_DIR;
@@ -53,8 +76,8 @@ function getInstructionMode(agent) {
   return 'legacy';
 }
 
-function buildAgyLaunchArgv({ contextFile, mode, sessionId, extraArgs }) {
-  const argv = [...extraArgs, '--add-dir', os.tmpdir()];
+function buildAgyLaunchArgv({ contextFile, scratchDir, mode, sessionId, extraArgs }) {
+  const argv = [...extraArgs, '--add-dir', scratchDir];
   if (mode === 'resume') {
     const agySessionId = sessionId?.trim();
     if (agySessionId) {
@@ -98,10 +121,29 @@ const agentIdentifierMap = {
 
 const supportedAgents = ['claude', 'codex', 'cursor', 'antigravity', 'opencode', 'pi'];
 
+// Re-exported under clearer names for the direct-launch dispatcher in index.mjs.
+export { supportedAgents as BUILTIN_LAUNCH_AGENTS, agentIdentifierMap };
+
 function shellQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
 
+/**
+ * Run an agent binary, optionally routed through a user-defined pre-command
+ * (e.g. `ollama` to run claude-code through Ollama). When a pre-command is set,
+ * its first token becomes the executable and the agent binary + args follow it:
+ *   preCommand="ollama"  →  ollama claude <args...>
+ */
+function execAgentBinary(binary, args, opts, preCommand) {
+  const pre = typeof preCommand === 'string' ? preCommand.trim() : '';
+  if (pre) {
+    const preTokens = pre.split(/\s+/).filter(Boolean);
+    execFileSync(preTokens[0], [...preTokens.slice(1), binary, ...args], opts);
+    return;
+  }
+  execFileSync(binary, args, opts);
+}
+
 function toTomlString(value) {
   return `"${String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
@@ -178,6 +220,9 @@ function buildRemoteLaunchCommand(agent, options) {
   if (options.launchMode === 'ask') {
     nestedParts.push('--launch-mode', 'ask');
   }
+  if (options.preCommand) {
+    nestedParts.push('--pre-command', shellQuote(options.preCommand));
+  }
   if (options.model) {
     nestedParts.push('--model', shellQuote(options.model));
   }
@@ -234,6 +279,7 @@ Options:
   --model <identifier>              Preferred model identifier
   --thinking <level>                Agent reasoning/effort level
   --flag <value>                    Extra agent flag (repeatable)
+  --pre-command <command>           Command to run before the agent binary (e.g. ollama)
   --ssh-command <command>           Launch remotely over SSH by running ovld on the target host
   --remote-working-directory <path> Change to this path on the remote host before launch
   --server-multiplexer <none|tmux>  Wrap remote launches in tmux
@@ -307,6 +353,10 @@ async function runAgent(agent, mode = 'run', options = {}) {
     process.chdir(options.workingDirectory);
   }
 
+  const scratchDir = resolveLaunchScratchDir(options.workingDirectory, {
+    explicit: Boolean(options.workingDirectory)
+  });
+
   const launchOrganizationId = resolveLaunchOrganizationId(
     ticketId,
     options.organizationId,
@@ -344,13 +394,13 @@ async function runAgent(agent, mode = 'run', options = {}) {
     agent
   );
 
-  const childEnv = {
+  const childEnv = withLaunchTempEnv({
     ...process.env,
     AGENT_IDENTIFIER: agentIdentifierMap[agent],
     ...(resolvedLaunchOrganizationId
       ? { OVERLORD_ORGANIZATION_ID: String(resolvedLaunchOrganizationId) }
       : {})
-  };
+  }, scratchDir);
   const extraArgs = buildExtraArgs(agent, options);
 
   try {
@@ -363,7 +413,7 @@ async function runAgent(agent, mode = 'run', options = {}) {
           : ['--continue', context];
         args.unshift(...extraArgs);
         if (pluginDir) args.unshift('--plugin-dir', pluginDir);
-        execFileSync('claude', args, { stdio: 'inherit', env: childEnv });
+        execAgentBinary('claude', args, { stdio: 'inherit', env: childEnv }, options.preCommand);
       } else {
         const args = [
           '--append-system-prompt',
@@ -372,11 +422,7 @@ async function runAgent(agent, mode = 'run', options = {}) {
           'Begin working on this ticket. Start by calling the attach endpoint, then proceed with the objective described in your system prompt.'
         ];
         if (pluginDir) args.unshift('--plugin-dir', pluginDir);
-        execFileSync(
-          'claude',
-          args,
-          { stdio: 'inherit', env: childEnv }
-        );
+        execAgentBinary('claude', args, { stdio: 'inherit', env: childEnv }, options.preCommand);
       }
     } else if (agent === 'codex') {
       if (mode === 'resume') {
@@ -385,12 +431,22 @@ async function runAgent(agent, mode = 'run', options = {}) {
           ? ['resume', codexSessionId, context]
           : ['resume', '--last', context];
         args.splice(1, 0, ...extraArgs);
-        execFileSync('codex', args, { stdio: 'inherit', env: childEnv });
+        execAgentBinary('codex', args, { stdio: 'inherit', env: childEnv }, options.preCommand);
       } else {
-        execFileSync('codex', [...extraArgs, context], { stdio: 'inherit', env: childEnv });
+        execAgentBinary(
+          'codex',
+          [...extraArgs, context],
+          { stdio: 'inherit', env: childEnv },
+          options.preCommand
+        );
       }
     } else if (agent === 'cursor') {
-      execFileSync('agent', [...extraArgs, context], { stdio: 'inherit', env: childEnv });
+      execAgentBinary(
+        'agent',
+        [...extraArgs, context],
+        { stdio: 'inherit', env: childEnv },
+        options.preCommand
+      );
     } else if (agent === 'opencode') {
       if (mode === 'resume') {
         const openCodeSessionId = process.env.OPENCODE_SESSION_ID?.trim();
@@ -398,12 +454,14 @@ async function runAgent(agent, mode = 'run', options = {}) {
           ? ['--continue', '--session', openCodeSessionId, '--prompt', context]
           : ['--continue', '--prompt', context];
         args.unshift(...extraArgs);
-        execFileSync('opencode', args, { stdio: 'inherit', env: childEnv });
+        execAgentBinary('opencode', args, { stdio: 'inherit', env: childEnv }, options.preCommand);
       } else {
-        execFileSync('opencode', [...extraArgs, '--prompt', context], {
-          stdio: 'inherit',
-          env: childEnv
-        });
+        execAgentBinary(
+          'opencode',
+          [...extraArgs, '--prompt', context],
+          { stdio: 'inherit', env: childEnv },
+          options.preCommand
+        );
       }
     } else if (agent === 'pi') {
       if (mode === 'resume') {
@@ -412,27 +470,34 @@ async function runAgent(agent, mode = 'run', options = {}) {
           ? ['--session', piSessionId, context]
           : ['--continue', context];
         args.unshift(...extraArgs);
-        execFileSync('pi', args, { stdio: 'inherit', env: childEnv });
+        execAgentBinary('pi', args, { stdio: 'inherit', env: childEnv }, options.preCommand);
       } else {
-        execFileSync('pi', [...extraArgs, context], { stdio: 'inherit', env: childEnv });
+        execAgentBinary(
+          'pi',
+          [...extraArgs, context],
+          { stdio: 'inherit', env: childEnv },
+          options.preCommand
+        );
       }
     } else if (agent === 'antigravity') {
       const tag = `overlord-${ticketId.slice(-8)}-${Date.now()}`;
-      const contextFile = path.join(os.tmpdir(), `${tag}-ctx.md`);
+      const contextFile = path.join(scratchDir, `${tag}-ctx.md`);
       fs.writeFileSync(contextFile, context, 'utf-8');
       setTimeout(() => { try { fs.unlinkSync(contextFile); } catch { /* already gone */ } }, 30 * 60_000).unref();
 
       const agySessionId =
         process.env.AGY_SESSION_ID?.trim() ?? process.env.GEMINI_SESSION_ID?.trim();
-      execFileSync(
+      execAgentBinary(
         'agy',
         buildAgyLaunchArgv({
           contextFile,
+          scratchDir,
           mode,
           sessionId: agySessionId,
           extraArgs
         }),
-        { stdio: 'inherit', env: childEnv }
+        { stdio: 'inherit', env: childEnv },
+        options.preCommand
       );
     }
   } catch (error) {
@@ -460,12 +525,89 @@ async function runAgent(agent, mode = 'run', options = {}) {
   }
 }
 
+/**
+ * Launch a user-defined custom agent. The resolved launch command (with all
+ * `{{token}}` placeholders already substituted) is passed via --command; we
+ * fetch the ticket context and run `<command> <context>` in the shell.
+ */
+async function runCustomAgent(args) {
+  const { flags } = parseLauncherArgs(args);
+  const command = typeof flags.command === 'string' ? flags.command.trim() : '';
+  const ticketId = typeof flags['ticket-id'] === 'string' ? flags['ticket-id'].trim() : '';
+  if (!command) {
+    console.error('Missing required option: --command "<resolved launch command>"');
+    process.exit(1);
+  }
+  if (ticketId) {
+    process.env.TICKET_ID = ticketId;
+  }
+  const resolvedTicketId = process.env.TICKET_ID;
+  if (!resolvedTicketId) {
+    console.error('Missing required environment variable: TICKET_ID');
+    process.exit(1);
+  }
+
+  if (typeof flags['working-directory'] === 'string' && flags['working-directory'].trim()) {
+    process.chdir(flags['working-directory'].trim());
+  }
+
+  const scratchDir = resolveLaunchScratchDir(flags['working-directory'], {
+    explicit: typeof flags['working-directory'] === 'string' && flags['working-directory'].trim().length > 0
+  });
+
+  const launchOrganizationId = resolveLaunchOrganizationId(
+    resolvedTicketId,
+    flags['organization-id'],
+    null
+  );
+  const { platformUrl, bearerToken, localSecret, organizationId } = await resolveAuth({
+    organizationIdHint: launchOrganizationId
+  });
+  const resolvedLaunchOrganizationId = resolveLaunchOrganizationId(
+    resolvedTicketId,
+    flags['organization-id'],
+    organizationId
+  );
+  // Custom agents have no Overlord plugin/bundle; use the generic "claude" context.
+  const context = await fetchContext(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    resolvedLaunchOrganizationId,
+    resolvedTicketId,
+    'claude'
+  );
+
+  const childEnv = withLaunchTempEnv({
+    ...process.env,
+    AGENT_IDENTIFIER: 'custom',
+    ...(resolvedLaunchOrganizationId
+      ? { OVERLORD_ORGANIZATION_ID: String(resolvedLaunchOrganizationId) }
+      : {})
+  }, scratchDir);
+
+  try {
+    execFileSync('sh', ['-lc', `${command} ${shellQuote(context)}`], {
+      stdio: 'inherit',
+      env: childEnv
+    });
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
 export async function runLauncherCommand(command, args) {
   if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
     printLauncherHelp();
     return;
   }
 
+  if (command === 'launch-custom') {
+    await runCustomAgent(args);
+    return;
+  }
+
   const normalizedCommand =
     command === 'launch' || command === 'connect'
       ? 'run'
@@ -486,6 +628,7 @@ export async function runLauncherCommand(command, args) {
     launchMode: flags['launch-mode'] === 'ask' ? 'ask' : 'run',
     model: typeof flags.model === 'string' ? flags.model.trim() : '',
     thinking: typeof flags.thinking === 'string' ? flags.thinking.trim() : '',
+    preCommand: typeof flags['pre-command'] === 'string' ? flags['pre-command'].trim() : '',
     flags: repeatedFlags,
     organizationId:
       typeof flags['organization-id'] === 'string' ? flags['organization-id'].trim() : '',

package/bin/_cli/setup.mjs

@@ -485,6 +485,24 @@ function writeManifest(manifest) {
   writeJsonFile(MANIFEST_FILE, manifest);
 }
 
+/**
+ * Quietly report whether an agent connector is installed: present in the bundle
+ * manifest with all of its recorded files still on disk. Unlike `doctorAgent`,
+ * this logs nothing and ignores version/hash staleness — a stale-but-present
+ * connector can still launch. Used to gate `ovld <agent>` direct launches.
+ */
+export function isAgentConnectorInstalled(agent) {
+  const manifest = readManifest();
+  const entry = manifest[agent];
+  if (!entry || !Array.isArray(entry.files)) return false;
+  return entry.files.every(file => fs.existsSync(file));
+}
+
+/** The built-in agents whose connectors are currently installed. */
+export function listInstalledConnectors() {
+  return supportedAgents.filter(agent => isAgentConnectorInstalled(agent));
+}
+
 function slashCommandFiles(agent) {
   if (agent === 'claude') {
     const base = path.join(os.homedir(), '.claude', 'commands');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "0.2605281741.0",
+  "version": "0.2605290912.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "homepage": "https://www.ovld.ai/docs/",
   "type": "module",