@sergeychuvayev/claude-fleet 0.1.0 → 0.2.0

package/bin/claude-fleet.js

@@ -13,18 +13,25 @@ const pkg = require(path.join(ROOT, 'package.json'))
 const HELP = `
   Claude Fleet v${pkg.version} — a local control room for Claude Code sessions
 
-  claude-fleet                 start Fleet and open the dashboard
-  claude-fleet start           start it without opening a browser
+  claude-fleet                 start Fleet and open it as an app window
+  claude-fleet start           start it without opening anything
+  claude-fleet --browser       open a normal browser tab instead of an app window
   claude-fleet install-app     put a "Claude Fleet" app in ~/Applications (macOS)
   claude-fleet update          install the latest published version
   claude-fleet --version       print the version
   claude-fleet --help          this
 
+  The app window is a Chromium window with no tab strip and no address bar. If Fleet
+  is already running, claude-fleet puts that server on screen rather than starting a
+  second one.
+
   Environment
     PORT                       port to listen on (default 7777, next free one if taken)
     CLAUDE_FLEET_HOME          where Fleet keeps its own state (default ~/.claude-fleet)
     CLAUDE_FLEET_DIR           the Claude directory to read (default ~/.claude)
     CLAUDE_FLEET_EXECUTABLE    the claude binary to run; "bundled" uses the SDK's own
+    CLAUDE_FLEET_BROWSER       the Chromium to open the app window with
+    CLAUDE_FLEET_APP_PROFILE   where that window keeps its profile
 `
 
 // A PATH walk rather than `command -v`, because this has to work without a shell

package/managed.js

@@ -78,22 +78,45 @@ class ManagedSessions extends EventEmitter {
       }
     } catch (error) { this.releaseLock(); throw new Error(`Cannot read Fleet session store: ${error.message}`) }
   }
+  // The lock used to hold a bare PID. It now holds {pid, port} so that a second
+  // `claude-fleet` can put the running dashboard on screen instead of only naming the
+  // process that beat it to the lock. A bare PID is still read: the file outlives an
+  // upgrade, and a stale one must not read as corrupt.
+  readLock() {
+    const raw = fs.readFileSync(this.lock, 'utf8').trim()
+    try {
+      const parsed = JSON.parse(raw)
+      if (Number.isInteger(parsed?.pid) && parsed.pid > 0) return { pid: parsed.pid, port: Number(parsed.port) || null }
+    } catch {}
+    const pid = Number(raw)
+    return Number.isInteger(pid) && pid > 0 ? { pid, port: null } : null
+  }
   acquireLock() {
     for (let attempt = 0; attempt < 2; attempt++) {
-      try { fs.writeFileSync(this.lock, String(process.pid), { flag: 'wx', mode: 0o600 }); return }
+      try { fs.writeFileSync(this.lock, JSON.stringify({ pid: process.pid }), { flag: 'wx', mode: 0o600 }); return }
       catch (error) {
         if (error.code !== 'EEXIST') throw error
-        const pid = Number(fs.readFileSync(this.lock, 'utf8'))
-        if (!Number.isInteger(pid) || pid <= 0) throw new Error(`Invalid Fleet lock file; inspect ${this.lock}.`)
-        try { process.kill(pid, 0) }
+        const held = this.readLock()
+        if (!held) throw new Error(`Invalid Fleet lock file; inspect ${this.lock}.`)
+        try { process.kill(held.pid, 0) }
         catch (e) { if (e.code === 'ESRCH') { fs.unlinkSync(this.lock); continue } }
-        throw new Error(`Fleet controls are already running (PID ${pid}). Open that server instead.`)
+        // Carries the holder so main() can open it rather than print and exit 1. Being
+        // already running is the normal case, not a failure.
+        const conflict = new Error(`Fleet controls are already running (PID ${held.pid})`)
+        conflict.code = 'FLEET_ALREADY_RUNNING'
+        conflict.holder = held
+        throw conflict
       }
     }
     throw new Error('Cannot acquire Fleet session lock')
   }
+  // Called once the server knows which port it actually got, which is not always the
+  // one it asked for: the listen path walks upwards past anything already bound.
+  recordPort(port) {
+    try { fs.writeFileSync(this.lock, JSON.stringify({ pid: process.pid, port }), { mode: 0o600 }) } catch {}
+  }
   releaseLock() {
-    try { if (fs.readFileSync(this.lock, 'utf8') === String(process.pid)) fs.unlinkSync(this.lock) } catch {}
+    try { if (this.readLock()?.pid === process.pid) fs.unlinkSync(this.lock) } catch {}
   }
   save() {
     clearTimeout(this.saveTimer); this.saveTimer = null

package/open.js

@@ -0,0 +1,94 @@
+'use strict'
+// How the dashboard gets on screen. Fleet is a desktop tool in everything but
+// packaging, so the default is a Chromium app window — no tab strip, no address
+// bar, its own Dock entry — rather than a tab that goes missing among forty others.
+//
+// The profile directory is shared with the bundle `install-app` builds, on purpose.
+// Chrome keys localStorage and window state to the profile, so a terminal launch and
+// a Spotlight launch have to point at the same one or they become two windows that
+// disagree about which sessions you had open.
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+// Tried in order. Chrome first because it is the likeliest to be installed and its
+// `--app` behaviour has been stable for years.
+const MAC_BROWSERS = [
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+]
+const UNIX_BROWSERS = ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'microsoft-edge', 'brave-browser']
+const WIN_BROWSERS = [
+  'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+  'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+  'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+]
+
+const executable = file => { try { fs.accessSync(file, fs.constants.X_OK); return true } catch { return false } }
+
+// Absolute paths are checked as given; bare names are walked down PATH, because an
+// app launched from Finder or a .desktop file has no shell to resolve them for it.
+function locate(candidate, { env, exists }) {
+  if (candidate.includes(path.sep) || candidate.includes('/')) return exists(candidate) ? candidate : null
+  for (const dir of (env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue
+    const full = path.join(dir, candidate)
+    if (exists(full)) return full
+  }
+  return null
+}
+
+// Kept in step with build/make-app.sh. If one of them moves, both move.
+function profileDir({ env = process.env, platform = process.platform, home = os.homedir() } = {}) {
+  if (env.CLAUDE_FLEET_APP_PROFILE) return path.resolve(env.CLAUDE_FLEET_APP_PROFILE)
+  if (platform === 'darwin') return path.join(home, 'Library', 'Application Support', 'ClaudeFleetApp')
+  if (platform === 'win32') return path.join(env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'ClaudeFleetApp')
+  return path.join(env.XDG_DATA_HOME || path.join(home, '.local', 'share'), 'ClaudeFleetApp')
+}
+
+// CLAUDE_FLEET_BROWSER wins outright, so an operator on a Chromium this does not know
+// about is never stuck with a plain tab.
+function findBrowser({ env = process.env, platform = process.platform, exists = executable } = {}) {
+  const known = platform === 'darwin' ? MAC_BROWSERS : platform === 'win32' ? WIN_BROWSERS : UNIX_BROWSERS
+  const candidates = env.CLAUDE_FLEET_BROWSER ? [env.CLAUDE_FLEET_BROWSER, ...known] : known
+  for (const candidate of candidates) {
+    const found = locate(candidate, { env, exists })
+    if (found) return found
+  }
+  return null
+}
+
+// The plain-tab route, for when no Chromium is installed or the operator asked for it.
+function browserCommand(url, platform) {
+  if (platform === 'darwin') return ['open', [url]]
+  if (platform === 'win32') return ['cmd', ['/c', 'start', '', url]]
+  return ['xdg-open', [url]]
+}
+
+// Returns what it did, so the caller can say so and the tests can assert on it without
+// launching anything: {mode:'app'|'browser', command, args}.
+function openDashboard(url, {
+  env = process.env,
+  platform = process.platform,
+  home = os.homedir(),
+  exists = executable,
+  spawn = require('node:child_process').spawn,
+  app = true,
+} = {}) {
+  const browser = app ? findBrowser({ env, platform, exists }) : null
+  const [command, args] = browser
+    // --app is what drops the tab strip and the address bar. The separate profile also
+    // keeps Fleet out of the way of whatever the operator has open for actual browsing.
+    ? [browser, [`--app=${url}`, `--user-data-dir=${profileDir({ env, platform, home })}`]]
+    : browserCommand(url, platform)
+  // Detached: the window has to outlive `claude-fleet` when the server is already up
+  // and this process is about to exit.
+  const child = spawn(command, args, { stdio: 'ignore', detached: true })
+  child.on('error', () => {})
+  child.unref()
+  return { mode: browser ? 'app' : 'browser', command, args }
+}
+
+module.exports = { openDashboard, findBrowser, profileDir, MAC_BROWSERS, UNIX_BROWSERS, WIN_BROWSERS }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sergeychuvayev/claude-fleet",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A local control room for Claude Code sessions",
   "keywords": [
     "claude",
@@ -29,6 +29,7 @@
     "catalog.js",
     "fleet.js",
     "managed.js",
+    "open.js",
     "paths.js",
     "permissions.js",
     "search.js",

package/server.js

@@ -12,6 +12,7 @@ const { SearchJobs, warm: warmSearch, WINDOW_DAYS: SEARCH_DAYS } = require('./se
 const { Archive } = require('./archive.js')
 const { Updater } = require('./update.js')
 const { defaultCwd } = require('./paths.js')
+const { openDashboard } = require('./open.js')
 const { version: VERSION } = require('./package.json')
 const HOST = '127.0.0.1'
 const MODEL_FALLBACK = [
@@ -226,7 +227,21 @@ function main(){
     child.unref()
     setTimeout(()=>process.exit(0),100).unref()
   }
-  try{app=createApp({restart})}catch(error){console.error(error.message);process.exit(1)}
+  try{app=createApp({restart})}catch(error){
+    // Already running is the everyday case, not a crash: put the window the operator
+    // asked for on screen and leave quietly. Exiting 1 with no window was the whole
+    // reason a second `claude-fleet` looked like a broken one.
+    if(error.code==='FLEET_ALREADY_RUNNING'){
+      // A lock written by an older Fleet carries no port, so fall back to the one this
+      // run would have asked for. Every lock written from here on records the real one.
+      const running=error.holder?.port||Number(process.env.PORT||7777)
+      const target=`http://${HOST}:${running}`
+      console.log(`\n  ${error.message} → ${target}\n`)
+      if(process.argv.includes('--open')) openDashboard(target,{app:!process.argv.includes('--browser')})
+      process.exit(0)
+    }
+    console.error(error.message);process.exit(1)
+  }
   let attempt=0,port=Number(process.env.PORT||7777)
   app.server.on('error',async error=>{
     if(error.code==='EADDRINUSE' && attempt++<10){app.server.listen(++port,HOST);return}
@@ -234,16 +249,14 @@ function main(){
   })
   app.server.on('listening',()=>{
     const url=`http://${HOST}:${app.server.address().port}`
+    // Write the port where the next `claude-fleet` will look for it.
+    app.manager.recordPort(app.server.address().port)
     console.log(`\n  Claude Fleet v${VERSION} → ${url}\n  Local dashboard + managed agents · ctrl-c to stop\n`)
     // Index transcripts in the background so the first question does not wait for it.
     setTimeout(()=>warmSearch().catch(()=>{}),1500).unref()
     // And ask npm whether there is a newer Fleet, well after the page has loaded.
     setTimeout(()=>app.updater.check().catch(()=>{}),5000).unref()
-    if(process.argv.includes('--open')) {
-      const opener=process.platform==='darwin'?'open':'xdg-open'
-      const child=require('node:child_process').spawn(opener,[url],{stdio:'ignore'})
-      child.on('error',()=>{});child.unref()
-    }
+    if(process.argv.includes('--open')) openDashboard(url,{app:!process.argv.includes('--browser')})
   })
   app.server.listen(port,HOST)
   let closing=false