@bill10/agent-007 0.6.2 → 0.6.4000

package/.env.example

@@ -0,0 +1,54 @@
+# Agent 007 settings. Everything is optional and commented out: the app runs on
+# its defaults (the values shown). Uncomment a line to change it, then restart.
+#
+# Read from ~/.agent-007/.env (`npx @bill10/agent-007 init` writes this file
+# there) and from a .env in the directory you start the app from. Precedence,
+# highest first: command-line flags, the real environment, ./.env,
+# ~/.agent-007/.env. AGENT007_CONFIG_DIR moves ~/.agent-007.
+
+# Port to listen on.
+# PORT=7007
+
+# Bind interface. 127.0.0.1 = localhost-only (safe default).
+# Set to 0.0.0.0 to accept remote connections — only behind Tailscale or another
+# trusted network, since the server spawns real shells. See docs/REMOTE.md.
+# HOST=127.0.0.1
+
+# Comma-separated extra browser origins allowed by the cross-origin check.
+# localhost and 127.0.0.1 are always allowed. Add your tailnet hostname to reach
+# the app from another machine. Bare hostnames or full origins both work; only
+# the hostname is used. A single `*` disables the check (not recommended).
+# ALLOWED_ORIGINS=mac-mini.tailXXXX.ts.net
+
+# The permission mode every Claude Code / Codex agent the app starts runs in,
+# unless something more specific says otherwise: flags already in the command
+# you type, a job card's own mode, or a mode picked in the job board's
+# "permissions" dropdown. One of: auto, acceptEdits, bypassPermissions, manual,
+# dontAsk, plan. Unset: each CLI's own default. Billion keeps its own mode.
+# CLAUDE_PERMISSION_MODE=bypassPermissions
+# CODEX_PERMISSION_MODE=bypassPermissions
+
+# Who may message whom. By default an agent that asks before acting cannot
+# message one that never asks, so it cannot borrow the other's permissions.
+# `open` lifts that rule for all your agents (messages are still labelled as
+# coming from another agent). It changes nothing when every agent runs in the
+# same kind of mode.
+# AGENT_MESSAGING=open
+
+# Billion, the always-on agent you talk to (docs/BILLION.md). On by default;
+# 0/false/off/no turns it off. It is also off whenever user accounts exist.
+# BILLION=0
+
+# Billion's own folder and git repo. Must be new or empty the first time.
+# BILLION_DIR=~/.agent-007/billion
+
+# Claude Code stops at a "do you trust this folder?" dialog the first time it
+# runs anywhere, and every job-board worker gets a brand-new worktree. By default
+# the app accepts it for board workers (it adds the worktree to ~/.claude.json
+# before the spawn, and answers "Yes" if the dialog still appears), so queued
+# jobs start on their own. A trusted worktree loads that repo's own
+# .claude/settings.json: its hooks run, and its permission allow rules can
+# pre-approve what a strict board mode would ask about. 0/false/off/no keeps
+# the dialog.
+# Hand-started agents always keep it.
+# TRUST_BOARD_WORKTREES=0

package/README.md

@@ -29,6 +29,29 @@ npm start
 
 Open [http://localhost:7007](http://localhost:7007). Click **+ Job** to queue work on the board, or **+ Agent** to start one by hand -- preset buttons (Claude Code, Codex, Gemini, Bash; PowerShell on a Windows server) fill in the command, or type your own under Advanced. Needs Node.js 20.12+ and Git ([full requirements](#requirements)).
 
+### Settings
+
+It works with no configuration. To change something, create a settings file:
+
+```bash
+npx @bill10/agent-007 init    # writes ~/.agent-007/.env, every line commented out
+```
+
+Uncomment what you want, then restart. The ones people change:
+
+| Setting | What it does |
+|---------|--------------|
+| `BILLION=0` | Turns off Billion, the always-on agent |
+| `HOST=0.0.0.0` + `ALLOWED_ORIGINS=<tailnet name>` | Reach it from your phone or another machine (behind Tailscale only, see [docs/REMOTE.md](docs/REMOTE.md)) |
+| `CLAUDE_PERMISSION_MODE` | Mode Claude Code agents start in, e.g. `bypassPermissions` |
+| `CODEX_PERMISSION_MODE` | The same for Codex |
+| `TRUST_BOARD_WORKTREES=0` | Keeps Claude Code's folder-trust prompt for job board workers |
+| `PORT` | Port to listen on (default `7007`) |
+
+Highest wins: command-line flags (`--port`), then environment variables, then
+a `.env` in the directory you start it from, then `~/.agent-007/.env`. The full
+list is in [Configuration](#configuration) and `--help`.
+
 ## Highlights
 
 - **A job board, not a babysitting job** -- Each card gets a fresh agent on its own worktree and branch. It moves To do -> In progress -> Review on its own and lands as a pull request (or a summary, for work that isn't code). Cards can also run on a cron schedule.
@@ -71,20 +94,15 @@ The job board reuses that same machinery: a dispatched job is an ordinary agent,
 
 ## Configuration
 
-Configure via environment variables, either inline or in a `.env` file. On
-startup `npm start` auto-loads `.env` if present (via Node's built-in
-`--env-file-if-exists`), and `npx @bill10/agent-007` loads a `.env` in the
-directory you run it from; variables already set in your environment win over
-the file. `npx @bill10/agent-007 --port 8080` overrides `PORT`, and
-`npx @bill10/agent-007 --help` lists the options. Everything the app saves
-lives in `~/.agent-007`. Copy the template to get going:
-
-```bash
-cp .env.example .env    # then edit; .env is gitignored
-npm start
-```
-
-Or set them inline:
+Settings are environment variables. Set them inline, in `~/.agent-007/.env`
+(`npx @bill10/agent-007 init` creates it from [`.env.example`](.env.example),
+every setting explained and commented out), or in a `.env` in the directory you
+start from. `npx @bill10/agent-007`, a global `agent-007` and `npm start` in a
+clone all read both files, and the startup log names the ones it loaded. Highest
+wins: flags (`--port 8080` overrides `PORT`), then the environment, then
+`./.env`, then `~/.agent-007/.env`. `--help` lists them all. Everything the app
+saves lives in `~/.agent-007` (`AGENT007_CONFIG_DIR` moves it, and the settings
+file with it).
 
 ```bash
 PORT=8080 npm start                       # Custom port (default: 7007)
@@ -156,17 +174,20 @@ Agent 007 runs on macOS, Linux, and Windows -- spawning agents, adding repos, an
 - **Linux:** `build-essential` and `python3` (`sudo apt install build-essential python3`)
 - **Windows:** [Visual Studio Build Tools](https://github.com/microsoft/node-pty#windows) with the C++ workload
 
+**An agent will not start: `"claude" is not installed, or not on the PATH Agent 007 was started with.`** The CLI the agent runs (`claude`, `codex` or `gemini`) was not found, and the message says how to install it. If it is installed, Agent 007 was started from somewhere with a shorter `PATH` than your shell (a launcher or a service manager, say); start it from a terminal where `which claude` finds it. Billion runs on Claude Code too, so without it Billion's tab says what to do instead: install Claude Code and press **Start** next to Billion, or restart with `BILLION=0` to turn Billion off.
+
 ## Architecture
 
 ```
 server.js          Entry point + orchestrators (createSession, killSession)
 server/
   state.js         Shared mutable state (sessions, orphans, pools, config)
+  settings.js      Config dir and the settings files (./.env, ~/.agent-007/.env)
   config.js        Config persistence (load, save, crash recovery)
   direct-run.js    Entry-point detection (symlink/space-safe `npm start` guard)
   git.js           Git operations (worktree, file tree, diff)
   jobs.js          Job board dispatcher (scan, spawn, PR watch, schedule firing, attachment files)
-  command-path.js  Resolves commands to spawnable files on Windows (PATHEXT)
+  command-path.js  Checks a CLI is installed before a spawn; resolves commands to spawnable files on Windows (PATHEXT)
   pty.js           PTY lifecycle (spawn, handlers, state detection)
   ws.js            WebSocket (message routing, broadcast, origin check, shared terminal sizing)
   http.js          HTTP routes (/api/browse, /api/jobs, job attachment downloads, /mcp, origin + auth gates)

package/VERSION

@@ -1 +1 @@
-0.6.2.1
+0.6.4.0

package/bin/agent-007.js

@@ -1,34 +1,55 @@
 #!/usr/bin/env node
-// agent-007 — the command `npx @bill10/agent-007` (or a global install) runs.
+// agent-007 — the command `npx @bill10/agent-007` (or a global install, or
+// `npm start` in a clone) runs.
 //
-// Loads ./.env from the current directory when there is one (the same file
-// `npm start` reads in a clone; variables already in the environment win),
-// applies --port over both, then starts server.js. Everything the server reads
-// or writes resolves from the package or from ~/.agent-007, so it runs the
-// same from node_modules as from a clone.
+// Loads settings (server/settings.js: ./.env, then ~/.agent-007/.env; the real
+// environment and --port win over both), then starts server.js. Everything the
+// server reads or writes resolves from the package or from ~/.agent-007, so it
+// runs the same from node_modules as from a clone.
 
-import { existsSync, readFileSync } from 'fs';
-import { resolve } from 'path';
+import { mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { basename, join } from 'path';
 import { fileURLToPath } from 'url';
 import { parseArgs } from 'util';
+import { configDir, loadSettings, settingsLine } from '../server/settings.js';
 
+// Each .env.example setting has a line here; test/cli.test.js checks that.
 const HELP = `Usage: agent-007 [--port <n>]
+       agent-007 init
        agent-007 adduser "Display Name"
 
 Starts Agent 007 at http://localhost:7007 (or --port).
 
+Commands:
+  init             Create ~/.agent-007/.env, a commented settings template
+  adduser          Create a login user and turn on login for the server
+
 Options:
   -p, --port <n>   Port to listen on (overrides PORT)
   -h, --help       Show this help
   -v, --version    Print the version
 
-Settings come from environment variables, or a .env file in the current
-directory: PORT, HOST, ALLOWED_ORIGINS, CLAUDE_PERMISSION_MODE,
-CODEX_PERMISSION_MODE, AGENT_MESSAGING, BILLION, BILLION_DIR.
-See https://github.com/bill10/agent-007#configuration
+Settings (default in brackets):
+  PORT                    Port to listen on [7007]
+  HOST                    Interface to bind; 0.0.0.0 to reach it from a phone
+                          or over Tailscale [127.0.0.1]
+  ALLOWED_ORIGINS         Extra hostnames the browser may use, comma-separated,
+                          e.g. your tailnet name [none]
+  CLAUDE_PERMISSION_MODE  Mode Claude Code agents start in: auto, acceptEdits,
+                          bypassPermissions, manual, dontAsk, plan [Claude's own]
+  CODEX_PERMISSION_MODE   The same for Codex agents [Codex's own]
+  AGENT_MESSAGING         open = any agent may message any other [guarded]
+  BILLION                 0 turns off Billion, the always-on agent [on]
+  BILLION_DIR             Billion's folder and repo [~/.agent-007/billion]
+  TRUST_BOARD_WORKTREES   0 keeps Claude Code's folder-trust prompt for job
+                          board workers [on]
+
+Set them in the environment, in ~/.agent-007/.env (\`agent-007 init\` writes it,
+every setting explained and commented out), or in a .env in the current
+directory. Highest first: flags, environment, ./.env, ~/.agent-007/.env.
 
 State lives in ~/.agent-007 (AGENT007_CONFIG_DIR to move it).
-\`adduser\` creates a login user and turns on login for the server.
+See https://github.com/bill10/agent-007#settings
 `;
 
 let parsed;
@@ -56,30 +77,49 @@ if (values.version) {
   process.exit(0);
 }
 
-// Said out loud: run from inside another project, its .env (a HOST=0.0.0.0,
-// say) would otherwise change this server without a word.
-if (existsSync('.env')) {
-  process.loadEnvFile('.env');
-  console.error(`  Loaded settings from ${resolve('.env')}`);
+if (values.port !== undefined) {
+  const port = Number(values.port);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    console.error(`--port must be a whole number from 1 to 65535, not "${values.port}"`);
+    process.exit(2);
+  }
+  // Before the files load, which never overwrite a variable already set.
+  process.env.PORT = String(port);
 }
+if (positionals.length && !['init', 'adduser'].includes(positionals[0])) {
+  console.error(`Unknown command: ${positionals[0]}\n\n${HELP}`);
+  process.exit(2);
+}
+
+const settingsFiles = loadSettings();
 
-if (positionals[0] === 'adduser') {
+// Said the way it was launched, so it can be pasted back.
+function initCommand() {
+  if (process.env.npm_command === 'exec') return 'npx @bill10/agent-007 init';
+  if (process.env.npm_lifecycle_event) return 'npm start -- init';
+  if (basename(process.argv[1] || '') === 'agent-007') return 'agent-007 init';
+  return 'npx @bill10/agent-007 init';
+}
+
+if (positionals[0] === 'init') {
+  const file = join(configDir(), '.env');
+  mkdirSync(configDir(), { recursive: true });
+  try {
+    // wx: never overwrite someone's settings.
+    writeFileSync(file, readFileSync(new URL('../.env.example', import.meta.url)), { flag: 'wx' });
+    console.log(`Created ${file}\nEvery setting in it is commented out, so nothing changes yet. Edit it, then restart agent-007.`);
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+    console.log(`${file} already exists, left as it is. Edit it, then restart agent-007.`);
+  }
+} else if (positionals[0] === 'adduser') {
   // adduser.js reads the display name from argv[2..].
   process.argv = [process.argv[0], fileURLToPath(new URL('./adduser.js', import.meta.url)), ...positionals.slice(1)];
   await import('./adduser.js');
 } else {
-  if (positionals.length) {
-    console.error(`Unknown command: ${positionals[0]}\n\n${HELP}`);
-    process.exit(2);
-  }
-  if (values.port !== undefined) {
-    const port = Number(values.port);
-    if (!Number.isInteger(port) || port < 1 || port > 65535) {
-      console.error(`--port must be a whole number from 1 to 65535, not "${values.port}"`);
-      process.exit(2);
-    }
-    process.env.PORT = String(port);
-  }
+  // Said out loud: run from inside another project, its .env (a HOST=0.0.0.0,
+  // say) would otherwise change this server without a word.
+  console.log(`  ${settingsLine(settingsFiles, initCommand())}`);
   // Imported only now: server/state.js reads PORT when it loads.
   const { startup, gracefulShutdown } = await import('../server.js');
   startup();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bill10/agent-007",
-  "version": "0.6.2",
+  "version": "0.6.4000",
   "description": "Self-hosted office where a manager agent posts jobs to Claude Code and Codex workers in parallel git worktrees, then reviews and merges their PRs. Cron jobs, agent-to-agent messaging, pixel-art status view.",
   "license": "MIT",
   "repository": {
@@ -14,6 +14,7 @@
     "agent-007": "bin/agent-007.js"
   },
   "files": [
+    ".env.example",
     "bin/",
     "lib/",
     "public/",
@@ -26,9 +27,9 @@
     "node": ">=20.12"
   },
   "scripts": {
-    "start": "node --env-file-if-exists=.env server.js",
-    "dev": "node --env-file-if-exists=.env --watch server.js",
-    "adduser": "node --env-file-if-exists=.env bin/adduser.js",
+    "start": "node bin/agent-007.js",
+    "dev": "node --watch bin/agent-007.js",
+    "adduser": "node bin/agent-007.js adduser",
     "test": "vitest run",
     "test:watch": "vitest"
   },

package/server/billion.js

@@ -150,6 +150,16 @@ export function billionCommand({ created, hasConversation, dir, projectsHint })
   return `claude --dangerously-skip-permissions${!created && hasConversation ? ' --continue' : ''} ${quote(prompt)}`;
 }
 
+// Billion is Claude Code. Without it, its tab runs this instead: one line
+// saying what to do, then an exit. Nothing restarts it, so there is no loop;
+// the Start button checks for claude again. It stays up a moment after
+// printing, since a console host can drop the output of a process that exits
+// at once.
+export const NO_CLAUDE_NOTICE = 'Billion runs on Claude Code, which is not installed (no "claude" on the PATH Agent 007 was started with). Install it from https://docs.anthropic.com/en/docs/claude-code/setup and press Start next to Billion, or restart Agent 007 with BILLION=0 to turn Billion off.';
+export function noClaudeCommand(node = process.execPath) {
+  return `${quote(node)} -e ${quote(`console.log(${JSON.stringify(NO_CLAUDE_NOTICE)}); setTimeout(() => {}, 1000)`)}`;
+}
+
 // Claude Code asks whether to trust a folder the first time it runs there, and
 // highlights "No, exit". Billion's folder is Agent 007's own, holding only
 // what the server put there, so the server answers for it. Board workers get

package/server/command-path.js

@@ -12,8 +12,8 @@
 // something the caller can try/catch. Resolving the command to a full path
 // with a launchable extension up front is what keeps it from happening.
 
-import { statSync } from 'fs';
-import { join, resolve } from 'path';
+import { statSync, accessSync, constants } from 'fs';
+import { join, resolve, delimiter } from 'path';
 
 const DEFAULT_PATHEXT = '.COM;.EXE;.BAT;.CMD';
 
@@ -100,3 +100,35 @@ export function isUsableCwd(dir) {
   if (!dir) return false;
   try { return statSync(dir).isDirectory(); } catch { return false; }
 }
+
+function isExecutable(p) {
+  try { accessSync(p, constants.X_OK); return statSync(p).isFile(); } catch { return false; }
+}
+
+/**
+ * Whether `file` would launch: a path to an executable, or a name on PATH.
+ *
+ * Checked before a spawn because on macOS and Linux node-pty "starts" a
+ * command that does not exist: the fork succeeds, the exec fails, and the tab
+ * shows an empty terminal that is already dead. Windows goes through
+ * resolveExecutable, the same lookup the spawn itself uses.
+ */
+export function commandExists(file, env = process.env, platform = process.platform, cwd = process.cwd()) {
+  if (!file) return false;
+  if (platform === 'win32') return !!resolveExecutable(file, env, platform, cwd);
+  if (file.includes('/')) return isExecutable(resolve(cwd, file));
+  return (env.PATH || '').split(delimiter).filter(Boolean).some(dir => isExecutable(join(dir, file)));
+}
+
+// Where to get the CLIs the + Agent presets and the board start.
+const INSTALL_HINTS = {
+  claude: 'Install Claude Code: https://docs.anthropic.com/en/docs/claude-code/setup',
+  codex: 'Install Codex: npm install -g @openai/codex',
+  gemini: 'Install Gemini CLI: npm install -g @google/gemini-cli',
+};
+
+// The one line a person sees when `file` is not there.
+export function missingCommandMessage(file) {
+  const hint = INSTALL_HINTS[file];
+  return `"${file}" is not installed, or not on the PATH Agent 007 was started with.${hint ? ` ${hint}` : ''}`;
+}

package/server/pty.js

@@ -6,7 +6,7 @@ import { basename } from 'path';
 import { stripAnsiComplete, detectState, createRingBuffer, parseCommand, isRealOutput, trackSyncFrames, ptyEnv } from '../lib/helpers.js';
 // Re-exported so the handler's tests reach the parser through the module they drive.
 export { trackSyncFrames } from '../lib/helpers.js';
-import { resolveExecutable, isUsableCwd } from './command-path.js';
+import { resolveExecutable, isUsableCwd, commandExists, missingCommandMessage } from './command-path.js';
 import { RING_BUFFER_MAX } from './state.js';
 import { mintAgentToken, authEnabled } from './auth.js';
 import { writeMcpConfig, removeMcpConfig, withMcpConfig, takesMcpConfig, withApprovalHook } from './agent-mcp.js';
@@ -218,6 +218,10 @@ export function createSessionFromConfig({ sessionId, name, color, command, repoP
   if (!isUsableCwd(cwd)) {
     return { error: `Working directory no longer exists: ${cwd}` };
   }
+  // A missing CLI "starts" on macOS and Linux and leaves a dead, empty tab.
+  if (!commandExists(file, process.env, process.platform, cwd)) {
+    return { error: missingCommandMessage(file) };
+  }
   // Falls back to the bare name when nothing matched, leaving node-pty's own
   // lookup (and its catchable "File not found") in charge.
   const resolvedFile = resolveExecutable(file, process.env, process.platform, cwd) || file;

package/server/settings.js

@@ -0,0 +1,42 @@
+// Where settings come from, for bin/agent-007.js (which `npm start` runs too).
+// Imports nothing from state.js: that module reads PORT and HOST when it loads,
+// so it may only be imported once the files below are in process.env.
+
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { join, resolve } from 'path';
+
+// Everything the app saves, and the settings file `agent-007 init` writes.
+export function configDir(env = process.env) {
+  return env.AGENT007_CONFIG_DIR || join(homedir(), '.agent-007');
+}
+
+// ./.env first, then <config dir>/.env. process.loadEnvFile never overwrites a
+// variable that is already set, so the real environment beats ./.env, and
+// ./.env beats the config-dir file. Returns the files it loaded.
+export function loadSettings() {
+  const files = [];
+  if (existsSync('.env')) {
+    process.loadEnvFile('.env');
+    files.push(resolve('.env'));
+  }
+  // Resolved after ./.env, which may set AGENT007_CONFIG_DIR.
+  const shared = join(configDir(), '.env');
+  if (existsSync(shared) && !files.includes(resolve(shared))) {
+    process.loadEnvFile(shared);
+    files.push(resolve(shared));
+  }
+  return files;
+}
+
+const tilde = (p) => {
+  const home = homedir();
+  return p.startsWith(home + '/') || p.startsWith(home + '\\') ? '~' + p.slice(home.length) : p;
+};
+
+// One startup line saying where settings came from, or how to make the file.
+export function settingsLine(files, initCommand) {
+  return files.length
+    ? `Settings: ${files.map(tilde).join(', ')}`
+    : `Settings: defaults (run \`${initCommand}\` to create ${tilde(join(configDir(), '.env'))})`;
+}

package/server/state.js

@@ -1,8 +1,8 @@
 // Shared mutable state — single owner for all Maps, Sets, and singletons.
 // All other modules import from here. No circular deps.
 
-import { homedir } from 'os';
 import { join } from 'path';
+import { configDir } from './settings.js';
 import {
   createCodenamePool, createCocktailPool, createColorCycler,
 } from '../lib/helpers.js';
@@ -69,7 +69,7 @@ export const GIT_USER_TIMEOUT = 30000;
 // (mirrors AGENT007_WORKTREE_DIR and AGENT007_USERS_PATH, both set by test/setup.js).
 // saveConfig() rewrites this file wholesale from in-memory state, so a test that
 // touches config would otherwise silently destroy the real repo/orphan list.
-export const CONFIG_DIR = process.env.AGENT007_CONFIG_DIR || join(homedir(), '.agent-007');
+export const CONFIG_DIR = configDir();
 // Overridable so tests never create worktrees in the developer's live
 // ~/.agent-007/worktrees (mirrors AGENT007_USERS_PATH, which test/setup.js uses).
 export const WORKTREE_DIR = process.env.AGENT007_WORKTREE_DIR || join(CONFIG_DIR, 'worktrees');

package/server.js

@@ -33,7 +33,9 @@ import { startDispatcher, stopDispatcher, boardSettings } from './server/jobs.js
 import { orphans, config } from './server/state.js';
 import { sweepMcpConfigs } from './server/agent-mcp.js';
 import { withDefaultPermission, envPermissionMode, PERMISSION_MODES, ENV_PERMISSION_MODE } from './lib/jobs.js';
-import { BILLION_NAME, billionEnabled, billionRuns, billionDir, ensureBillionRepo, refreshCharter, suggestProjectsDir, billionCommand } from './server/billion.js';
+import { BILLION_NAME, billionEnabled, billionRuns, billionDir, ensureBillionRepo, refreshCharter, suggestProjectsDir, billionCommand, noClaudeCommand } from './server/billion.js';
+import { commandExists, missingCommandMessage } from './server/command-path.js';
+import { parseCommand } from './lib/helpers.js';
 import { hasClaudeTranscript } from './server/agent-transcripts.js';
 import { autoTrusts, trustClaudeFolder } from './server/claude-trust.js';
 
@@ -57,6 +59,10 @@ async function createSession(command, name, repoPath, customBranch, ownerId, met
   // worktree directory's codename: two holders of one name means the first
   // kill frees it while the other still names a directory on disk.
   if (name && codenamePool.has(name)) return { error: `An agent named ${name} already exists` };
+  // A missing CLI, before any worktree is made for it: the board retries a
+  // failed card every tick. A path is left to the spawn, which knows the cwd.
+  const { file } = parseCommand(command);
+  if (!/[\\/]/.test(file) && !commandExists(file)) return { error: missingCommandMessage(file) };
   // An agent someone starts gets the .env default mode for its CLI, unless its
   // command already says how it asks. The board settles its own workers' mode
   // (boardModeFor in server/jobs.js), so their commands are left as built.
@@ -190,12 +196,13 @@ function startBillion() {
       console.error(`Billion: could not commit the updated charter in ${dir}:`, err.message);
     }
   }
-  const command = billionCommand({
+  const hasClaude = commandExists('claude', process.env, process.platform, dir);
+  const command = hasClaude ? billionCommand({
     created,
     hasConversation: !created && hasClaudeTranscript(dir),
     dir,
     projectsHint: suggestProjectsDir(config.repos.map(r => r.path)),
-  });
+  }) : noClaudeCommand();
   const result = createSessionFromConfig({
     sessionId: nextSessionId(), name: BILLION_NAME, color: colorCycler.next(), command,
     repoPath: null, worktreePath: null, cwd: dir, isBillion: true, ownerId: null,
@@ -205,7 +212,7 @@ function startBillion() {
   // introduction, and at the start of every cycle after a restart.
   result.session.messagesHeld = true;
   sessions.set(result.session.id, result.session);
-  return { session: result.session };
+  return { session: result.session, ...(hasClaude ? {} : { notice: 'Claude Code (claude) is not installed; its tab says how to fix that' }) };
 }
 
 // --- WebSocket ---
@@ -245,8 +252,8 @@ async function startup() {
     else if (raw) console.log(`  ${agent} agents start in ${raw} unless told otherwise`);
   }
   if (billionRuns()) {
-    const { error } = startBillion();
-    console.log(error ? `  Billion: not started (${error})` : `  Billion: running in ${billionDir()}`);
+    const { error, notice } = startBillion();
+    console.log(error ? `  Billion: not started (${error})` : notice ? `  Billion: ${notice}` : `  Billion: running in ${billionDir()}`);
   } else if (billionEnabled()) {
     console.log('  Billion: off while user accounts are enabled');
   }