il start fails on Linux: terminal window launching not supported

[TickTockBent]

Summary

il start (both epic/swarm mode and single-issue mode) fails on Linux because the terminal window launching mechanism is macOS-only. This makes the core workspace workflow unusable on Linux.

Environment

Property	Value
CLI Version	0.10.2
OS	Ubuntu Linux 6.8.0-90-generic
IDE	Code Server (browser-based VS Code)
Claude CLI	Available and working

Reproduction Steps

# Single issue mode
il start 9 --no-code --no-dev-server
# → ❌ Terminal window launching not yet supported on linux

# Epic/swarm mode
il start 9 --no-code --no-dev-server --epic
# → ❌ Terminal window launching not yet supported on linux

Errors Encountered (in order)

1. VS Code code command not found

❌ Visual Studio Code is configured as your IDE but "code" command was not found.

Context: Using Code Server (browser-based VS Code), which doesn't provide a code CLI command. Workaround: --no-code flag bypasses this.

Suggestion: Detect code-server as an alternative, or surface a clearer setting to configure the IDE command.

2. Non-interactive environment detection

❌ Non-interactive environment detected, use either --epic or --no-epic to specify behavior

Context: Running inside a Claude Code terminal session. Workaround: pass --epic or --no-epic explicitly.

3. Terminal window launching not supported (blocker)

❌ Terminal window launching not yet supported on linux. Currently only macOS is supported.
❌ Failed to start workspace: Terminal window launching not yet supported on linux.

Context: This is the hard blocker. Even with --no-code and --no-dev-server, il start still tries to spawn a native terminal window and fails. There is no flag to bypass this — the workspace cannot be created at all on Linux.

The Claude agent launch also fails before reaching this point:

❌ Failed to launch Claude for workflow { "error": {} }

Impact

• il start <issue> — completely broken on Linux
• il start <epic> --epic (swarm mode) — completely broken on Linux
• All workspace creation is blocked, making iloom unusable for its primary workflow on Linux

Suggestions

1. Headless/tmux mode: On Linux (or when no GUI terminal is available), launch Claude agents in tmux sessions, screen sessions, or background processes instead of native terminal windows. This would also benefit SSH and container-based workflows.

2. --headless flag: Allow il start to create the worktree and launch the Claude agent without requiring a terminal window at all — just run the process and stream output to stdout or a log file.

3. Code Server detection: Recognize code-server as a valid VS Code alternative for the IDE integration.

Related

• iloom is only tested on Mac. It will probably somewhat work on linux, and maybe WSL. Windows is anyone's guess. #256 — Broad tracking issue for cross-platform support
• VSCode is installed but 'code' is not available in the PATH - should be detected by init/config #372 — VS Code code command detection (closed, but the Code Server variant of this problem persists)

[TickTockBent]

Additional Finding: --one-shot mode also fails

One-shot mode does not bypass the terminal window requirement. The internal options show "headless": false even when --one-shot is passed:

il start 10 --no-code --no-dev-server --no-epic --one-shot default

❌ Failed to launch Claude for workflow {
  "error": {},
  "options": {
    "type": "issue",
    "workspacePath": "/home/ticktockbent/projects/infrastructure/ape_my-looms/feat-issue-10__base-path-prefix-support",
    "port": 5010,
    "headless": false,
    "oneShot": "default",
    ...
  }
}
❌ Terminal window launching not yet supported on linux. Currently only macOS is supported.
❌ Failed to start workspace: Terminal window launching not yet supported on linux.

Note that headless: false is set despite --one-shot being passed. There is no --headless flag available to override this.

Every il start invocation fails on Linux — single issue, epic/swarm, and one-shot modes all hit the same terminal window blocker. This means iloom cannot create any workspaces on Linux at all, making the tool effectively unusable on the platform. The only commands that work are non-workspace operations like il plan, il a, etc.

The worktree creation itself succeeds (branches and worktree directories are created), but the Claude agent launch and terminal window step always fails, leaving orphaned worktrees that need manual cleanup.

[TickTockBent]

Fix submitted: PR #796

PR #796 adds pluggable terminal backends that resolve all the issues reported here:

1. Terminal window launching on Linux — now supported via 3 backends:

   • GUI: gnome-terminal, konsole, xterm (auto-detected)
   • Headless (tmux): Falls back automatically when no GUI terminal is found — this covers SSH, Docker, Code Server, and CI environments
   • WSL: Windows Terminal via wt.exe

2. --one-shot still requires terminal window — fixed by the tmux backend handling headless mode transparently. No --headless flag needed; the factory detects the environment and picks the right backend.

3. Code Server code command — not addressed in this PR (orthogonal to terminal launching), but with tmux backend support, --no-code + the tmux fallback provides a complete workaround.

The architecture uses a strategy pattern (TerminalBackend interface) with a factory that selects the backend based on platform detection. Public API (openTerminalWindow, openMultipleTerminalWindows) is unchanged.

[acreeger]

Thanks for the PR! Will take a look!

[TickTockBent]

Great! Unfortunately until the other issue I raised has a workaround or fix it's still not usable on Linux but this tmux PR should get you a fair way towards Linux compatibility. I can't take all of the credit, I'm just building on top of the other PR I mentioned

[acreeger]

I just merged my fix for the other issue, so with this one, it should be pretty much there!

By the way. the --no-claude --no-terminal flags were the ones that you were missing when trying to work around it! They don't try to open any terminal windows.

Thanks again and thank you to and @rexsilex for this awesome contribution - can't wait to merge it!