keep-app-running

# Keep App Running Run long-lived local processes through `scripts/appctl` so they survive the transient shell that launched them. Treat a successful launch as incomplete until the process passes a health check. ## Start an app 1. Determine the repository root, working directory, start command, and expected URL or port from project files. Do not invent a command when it cannot be inferred safely. 2. Derive a stable session name: `codex-<repo>-<service>`. Use only letters, digits, underscores, and hyphens. 3. Start through the bundled controller: ```bash <skill-dir>/scripts/appctl start \ --name codex-example-web \ --cwd /absolute/path/to/repo \ --url http://127.0.0.1:3000 \ --wait 30 \ -- npm run dev ``` Use `--port 3000` when an HTTP URL is unavailable. Prefer a URL because it verifies the app protocol rather than only the listening socket. If neither is known, the controller performs only a process-liveness check; disclose that weaker verification. 4. Report the verified URL or port, tmux session name, and working directory. Do not claim success if the health check fails. 5. On failure, inspect retained output with `appctl logs --name <name>` and diagnose it. ## Manage an app ```bash appctl status --name codex-example-web appctl logs --name codex-example-web --lines 200 appctl restart --name codex-example-web --wait 30 appctl stop --name codex-example-web ``` Use the absolute path to the bundled `scripts/appctl` unless it is already on `PATH`. ## Safety rules - Never kill a process merely because it occupies the desired port. Identify ownership and ask before disrupting an unrelated process. - Never take over a pre-existing tmux session not marked as managed by this skill. - Reuse a healthy managed session rather than starting a duplicate. - Preserve a failed pane and its logs for diagnosis. - Stop only the named managed session requested by the user. Never use broad tmux cleanup commands. - Keep secrets out of session names, command arguments, and status output. Inherit secrets through the process environment when needed. - Use project-native durable orchestration such as Docker Compose when the project already depends on it; tmux may still durably own the foreground Compose command. ## Design details Read [references/design.md](references/design.md) when changing lifecycle behavior, adding stack detection, or reasoning about ownership and failure semantics.