@bill10/agent-007 0.6.3000 → 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)
@@ -164,6 +182,7 @@ Agent 007 runs on macOS, Linux, and Windows -- spawning agents, adding repos, an
 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)

package/VERSION

@@ -1 +1 @@
-0.6.3.0
+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.3000",
+  "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/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');