@bill10/agent-007 0.6.3000 → 0.6.4001

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

@@ -3,14 +3,23 @@
 [![Tests (Ubuntu)](https://github.com/bill10/agent-007/actions/workflows/test-ubuntu.yml/badge.svg)](https://github.com/bill10/agent-007/actions/workflows/test-ubuntu.yml)
 [![Tests (Windows)](https://github.com/bill10/agent-007/actions/workflows/test-windows.yml/badge.svg)](https://github.com/bill10/agent-007/actions/workflows/test-windows.yml)
 
-**Queue coding jobs, walk away, review the PRs.**
-
-Agents run in parallel, each in its own git worktree; one boss agent runs the board for you; and a pixel office shows who's working and who's waiting on you.
+**From web terminals for your coding agents to a self-running agent company.**
 
 ![An agent walks to its desk and starts work, a job card is posted and dispatched to a second desk, and an agent turns orange when it stops to ask a question](docs/demo.gif)
 
 *Recorded from the running app. If the capture does not load, there is a [still screenshot](docs/screenshot.png).*
 
+Use it as far along as you need:
+
+1. **One task: one agent in a web terminal.** Start Claude Code, Codex or any CLI agent in the browser. Add a repo once; every agent gets its own git worktree and branch, so you never set one up by hand.
+2. **Many tasks across projects: many terminals, one window.** Every repo and every agent in one place, with live terminals, a file explorer, inline diffs, and a pixel office where each agent faces its screen while it works and turns to you when it needs you.
+3. **Stop watching them: a job board.** Put tasks on the board and Claude Code or Codex workers pick them up, each in its own worktree, and move them To do -> In progress -> Review on their own, landing as a pull request (or a summary, for work that isn't code). Cards can run on a cron schedule, and agents can post cards and message each other.
+4. **Stop posting jobs: give Billion a goal.** Billion is one always-on agent that plans, posts the jobs, reviews what comes back and merges the PRs. It only asks you about money, access or anything irreversible.
+
+Claude Code, Codex, any terminal agent is supported -- use your existing subscriptions, no extra charge.
+
+It runs locally on your machine, so agents work while it is on and awake. Billion's plan and memory live in a git repo, so it picks up where it left off after a restart. Every worker is a real terminal you can open and type into, from your phone too ([remote access](docs/REMOTE.md)).
+
 ## Quick Start
 
 ```bash
@@ -29,15 +38,30 @@ 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)).
 
-## Highlights
+### 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:
 
-- **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.
-- **Billion, the one agent you talk to** -- Give it a mission and it plans, posts cards, reviews what comes back, merges PRs and answers its workers' permission requests. It comes to you only for money, access, anything irreversible and real forks in direction.
-- **Your agents, your subscriptions** -- Claude Code, Codex, any terminal agent is supported -- use your existing subscriptions, no extra charge.
-- **See everything at a glance** -- Every agent gets a desk in the pixel office: facing the screen while it works, turning to face you when it needs you. One window for every repo, with live terminals, a file explorer and inline diffs.
-- **Agents that talk to each other** -- Tell one to "add that to the job board" or "ask Viper what it changed", and it does it over MCP.
+| 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`) |
 
-Everything else -- scheduled jobs, phone layout, voice input, themes, and the details and caveats of each feature -- is in [docs/FEATURES.md](docs/FEATURES.md).
+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`.
+
+The details and caveats of every feature -- phone layout, voice input, themes and more -- are in [docs/FEATURES.md](docs/FEATURES.md).
 
 ## Keyboard Shortcuts
 
@@ -71,20 +95,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 +183,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.1

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,7 +1,7 @@
 {
   "name": "@bill10/agent-007",
-  "version": "0.6.3000",
-  "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.",
+  "version": "0.6.4001",
+  "description": "From web terminals for your coding agents to a self-running agent company: Claude Code and Codex in parallel git worktrees, a job board they pick work from, and one agent that runs the board from a goal.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -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"
   },
@@ -51,6 +52,7 @@
     "coding-agents",
     "ai-agents",
     "agent-orchestration",
+    "autonomous-agents",
     "parallel-agents",
     "git-worktree",
     "job-board",

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');