feat!: change gobfile autostart default to false

Jobs now default to autostart=false, meaning they are created but not
started when the TUI opens. Add autostart=true explicitly to jobs that
should auto-start and auto-stop with the TUI lifecycle.

This gives users manual control by default, which is safer for jobs
that may have side effects or consume resources.

Author: juanibiapina

CHANGELOG.md

@@ -17,12 +17,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Version negotiation no longer auto-restarts daemon**: When client and daemon versions mismatch, the client now returns an error instead of auto-restarting the daemon. This prevents old TUIs from restarting the daemon with their old binary, undoing upgrades. Users must now run `gob shutdown` and restart their clients when upgrading.
 - **TUI quits on daemon disconnect**: The TUI no longer attempts to reconnect when the daemon stops. Instead, it quits with a message asking the user to restart. This complements the version negotiation change by preventing old TUIs from resurrecting the daemon.
 - **Daemon no longer auto-shuts down when idle**: The daemon now runs indefinitely until explicitly stopped with `gob shutdown`.
+- **BREAKING: Gobfile `autostart` now defaults to `false`**: Jobs in the gobfile no longer auto-start by default. Add `autostart = true` to jobs that should start when the TUI opens and stop when it exits. Jobs without `autostart` (or with `autostart = false`) are created but not started, giving you manual control over their lifecycle.
 
 ### Fixed
 
 - **Runs panel column misalignment**: Fixed status column padding using byte length instead of visual width, causing misaligned columns when Unicode status icons (✓, ◉, ◼) were displayed.
 - **Gobfile descriptions not displayed**: Fixed job descriptions from gobfile not appearing in TUI when job already existed without a description.
-- **Gobfile auto-stop killing manually started jobs**: Jobs with `autostart = false` in the gobfile are no longer stopped when the TUI exits. Previously, if you defined a job with `autostart = false` and manually started it, it would be killed on TUI exit. Now only jobs with `autostart = true` (the default) are auto-stopped.
+- **Gobfile auto-stop killing manually started jobs**: Jobs with `autostart = false` in the gobfile are no longer stopped when the TUI exits. Previously, if you defined a job with `autostart = false` and manually started it, it would be killed on TUI exit. Now only jobs with `autostart = true` are auto-stopped.
 
 ## [3.0.0-rc.2] - 2026-01-25
 

docs/gobfile.md

@@ -12,15 +12,16 @@ A gobfile is a TOML configuration file that defines jobs for your project. When
 [[job]]
 command = "npm run dev"
 description = "Development server for the frontend app"
+autostart = true  # Start when TUI opens, stop when TUI exits
 
 [[job]]
 command = "npm run build:watch"
 description = "Watches TypeScript and rebuilds on change"
-autostart = false
+# autostart defaults to false - start manually, keeps running after TUI exits
 
 [[job]]
 command = "docker compose up db"
-# description and autostart are optional
+# description is optional, autostart defaults to false
 ```
 
 ## Fields
@@ -29,7 +30,7 @@ command = "docker compose up db"
 |-------|------|----------|---------|-------------|
 | `command` | string | Yes | - | The command to run |
 | `description` | string | No | - | Context about the job, shown in TUI and CLI |
-| `autostart` | boolean | No | `true` | Whether to auto-start when TUI opens and auto-stop when TUI exits |
+| `autostart` | boolean | No | `false` | Whether to auto-start when TUI opens and auto-stop when TUI exits |
 
 ## Behavior
 
@@ -38,14 +39,13 @@ command = "docker compose up db"
 1. Gobfile is parsed from `.config/gobfile.toml`
 2. For each job in the file:
    - If a job with the same command exists and is running: update description if different
-   - If a job with the same command exists and is stopped: restart it (if `autostart = true`)
-   - If no matching job exists: create and start it (if `autostart = true`)
-   - If `autostart = false`: create but don't start (shows as stopped)
+   - If `autostart = true`: create and start the job (or restart if stopped)
+   - If `autostart = false` (the default): create but don't start (shows as stopped)
 3. Jobs are started asynchronously (TUI doesn't wait for them)
 
 ### When TUI Exits
 
-Jobs with `autostart = true` (the default) are stopped when the TUI exits:
+Jobs with `autostart = true` are stopped when the TUI exits:
 - Normal exit (pressing `q`)
 - Terminal close
 - SIGTERM/SIGINT signals
@@ -69,14 +69,17 @@ Define all services needed for local development:
 [[job]]
 command = "npm run dev"
 description = "Next.js dev server on port 3000"
+autostart = true
 
 [[job]]
 command = "npm run api:dev"
 description = "API server on port 4000"
+autostart = true
 
 [[job]]
 command = "docker compose up postgres redis"
 description = "Database and cache services"
+autostart = true
 ```
 
 ### Build Watchers
@@ -87,11 +90,12 @@ Add watchers that rebuild on file changes:
 [[job]]
 command = "npm run typecheck:watch"
 description = "TypeScript type checking in watch mode"
+autostart = true  # Always run type checking
 
 [[job]]
 command = "npm run test:watch"
 description = "Jest tests in watch mode"
-autostart = false  # Start manually, keeps running after TUI exits
+# autostart defaults to false - start manually when needed
 ```
 
 ### AI Agent Context
@@ -102,15 +106,17 @@ Descriptions help AI agents understand what each job does:
 [[job]]
 command = "npm run dev"
 description = "Frontend dev server. Check this for UI errors. Runs on http://localhost:3000"
+autostart = true
 
 [[job]]
 command = "npm run api"
 description = "Backend API. Check logs here for request/response debugging"
+autostart = true
 
 [[job]]
 command = "npm run storybook"
 description = "Component library browser. Use for visual component testing"
-autostart = false
+# autostart defaults to false - start manually when needed
 ```
 
 When an AI agent runs `gob list`, it sees the descriptions and understands the purpose of each job.
@@ -155,14 +161,15 @@ echo ".config/gobfile.toml" >> .gitignore
 
 ### Jobs not starting
 
-1. Check the file location: must be `.config/gobfile.toml` (not project root)
-2. Verify TOML syntax: use a TOML validator
-3. Check daemon logs: `$XDG_STATE_HOME/gob/daemon.log`
+1. Check `autostart = true` is set - jobs default to `autostart = false` (not auto-started)
+2. Check the file location: must be `.config/gobfile.toml` (not project root)
+3. Verify TOML syntax: use a TOML validator
+4. Check daemon logs: `$XDG_STATE_HOME/gob/daemon.log`
 
 ### Jobs restarting unexpectedly
 
 Jobs are restarted if they were stopped and match a gobfile entry with `autostart = true`. To prevent this, either:
-- Set `autostart = false` for jobs you want to control manually
+- Remove `autostart = true` (jobs default to not auto-starting)
 - Remove the job from the gobfile
 
 ### Description not showing

internal/tui/gobfile.go

@@ -22,13 +22,13 @@ type GobfileConfig struct {
 type GobfileJob struct {
 	Command     string `toml:"command"`
 	Description string `toml:"description"`
-	Autostart   *bool  `toml:"autostart"` // nil defaults to true
+	Autostart   *bool  `toml:"autostart"` // nil defaults to false
 }
 
-// ShouldAutostart returns whether the job should be auto-started (defaults to true)
+// ShouldAutostart returns whether the job should be auto-started (defaults to false)
 func (j GobfileJob) ShouldAutostart() bool {
 	if j.Autostart == nil {
-		return true
+		return false
 	}
 	return *j.Autostart
 }