agent-tui

🚨 CRITICAL: macOS Daemon Workaround & Gemini CLI Usage 🚨

When using agent-tui in this macOS environment, the default background daemonization process crashes, causing Connection refused (os error 61) errors.

You MUST start the daemon manually shielded from TTY hangups before running any agent-tui commands. Using nohup is insufficient; you must use tmux to provide a fully isolated pseudo-terminal.

To support parallel runs, only restart the daemon if it is not currently running:

# Check if daemon is alive, start it in tmux if it is not
if ! agent-tui sessions >/dev/null 2>&1; then
  tmux kill-session -t agent-tui 2>/dev/null || true
  agent-tui daemon stop 2>/dev/null || true
  rm -f /tmp/agent-tui*
  tmux new-session -d -s agent-tui 'agent-tui daemon start --foreground > /tmp/agent-tui-daemon.log 2>&1'
  sleep 1
fi

Session ID vs PID (Crucial for Reconnection)

When agent-tui run returns JSON, it includes both a session_id and a pid. The pid is purely informational (the OS process ID of the child command). You do not use the pid to reconnect or issue commands. You must always use the session_id (e.g., --session <id>).

If the daemon crashes (os error 61), the pseudo-terminal is destroyed. Even if the child pid survives as an orphan, you cannot reconnect to it. You must restart the daemon using the workaround above and start a completely new session.

Testing the Gemini CLI

When testing the Gemini CLI with agent-tui, there are several strict requirements to ensure deterministic and accurate behavior:

1. Build Before Running: agent-tui runs the built JS files, not TypeScript. You MUST run npm run build or npm run build:all after making code changes and before launching the CLI with agent-tui.
2. Bypass Trust Modals: Always pass GEMINI_CLI_TRUST_WORKSPACE=true in the environment. If you don't, any new project-level agents or extensions will trigger a full-screen "Acknowledge and Enable" modal. This modal steals focus, swallows automation keystrokes, and causes agent-tui wait commands to time out.
3. Isolated Environments: If you need to test without real user credentials or existing agents interfering, isolate the global settings using GEMINI_CLI_HOME=<some-test-dir>.
4. Testing State Deltas (e.g., Reloads): If you are testing features that report deltas (e.g., /agents reload outputting "1 new local subagent"), you MUST:
   • Start the CLI first so it establishes its baseline registry.
   • Use a separate shell command (outside of agent-tui) to write the new agent .md/.toml file.
   • Use agent-tui type and press to trigger the /agents reload command inside the running session.
   • (If you add the files before starting the CLI, they become part of the baseline and won't trigger the delta logic).