Skill: Refine PTY and background requirements per command

[helixclaw]

Findings

Tested all major iloom commands from an AI agent (OpenClaw) to determine which actually require PTY mode and/or background execution.

Commands that work WITHOUT PTY (plain exec)

These return clean JSON output and complete quickly:

Command	Tested	Notes
il list --json	✅	Fast, clean JSON
il issues --json	✅	Fast, clean JSON
il projects --json	✅	Fast, clean JSON
il recap --json	✅	Fast, reads local file
il --version	✅	Instant
il start <issue> --no-claude --no-code --no-dev-server --json	✅	Takes ~15s (pnpm install), but works fine without PTY
il cleanup --issue <N> --force --json	✅	Fast, clean JSON
il finish --force --cleanup --no-browser --json	⚠️	Not tested directly but should work (no interactive prompts with these flags)
il commit --no-review --json	⚠️	Not tested but should work (no interactive prompts)

Commands that NEED background mode (launch Claude/long-running)

These spawn Claude Code sessions that can run 1-10+ minutes:

Command	Needs PTY?	Needs Background?	Notes
il plan --yolo --print --json-stream	Needs testing	✅ Yes	Opus planning can take 3-10 min
il spin --yolo --print --json-stream	Needs testing	✅ Yes	Full implementation sessions
il start <issue> --yolo --json (with Claude)	Yes	✅ Yes	Launches Claude via --startAiAgent
il summary --json	Needs testing	✅ Yes	Launches Claude for summarization
il enhance <N> --no-browser --json	Needs testing	✅ Yes	Launches Claude for enhancement

Commands that NEED foreground PTY (interactive)

Command	Notes
il init	Interactive wizard with Claude Code - not recommended for AI agents
il shell	Opens interactive subshell
il rebase	May need Claude for conflict resolution

Recommendation for SKILL.md

The current skill doc says "Always use pty:true for every iloom command." This is overly conservative. The updated guidance should be:

1. No PTY needed: list, issues, projects, recap, cleanup, start --no-claude, commit --no-review, finish --force
2. Background + PTY: plan, spin, start (with Claude), summary, enhance
3. Foreground PTY only: init, shell, rebase

Open Question

Do plan --print --json-stream and spin --print --json-stream actually need PTY? Since --print puts them in headless mode, they might work without PTY. Worth testing — if they work without PTY, we can simplify the guidance further to: "only use PTY for interactive commands (init, shell, rebase)."

Context

These findings came from real usage building the voice-bridge project via OpenClaw. The "always PTY" rule caused unnecessary complexity and the timeout issues led to multiple failed il init attempts before switching to manual setup.

[NoahCardoza]

You make a very good point. By using the YOLO flag, we don't need to use PTY even on the three commands I mentioned.

The one thing I'm worried about is with the finish and commit commands, there could be a timeout that happens if we don't run it in the background since some repositories have extensive testing suites. There is an ability to configure the timeout for iloom itself. So let's instruct the LLM to look that value and make sure that it doesn't set any timeout shorter than the value specified in the settings for the git commit when it comes to committing and finishing commands. The default is 30 seconds in iloom, so we should fall back to that If nothing is explicitly listed in the settings.

Other than these comments, this looks good to go.