fn_registry/bash/functions/infra/launch_fleetclaude.md

---
name: launch_fleetclaude
kind: function
lang: bash
domain: infra
version: "1.6.0"
purity: impure
signature: "launch_fleetclaude [--cwd <dir>] [--bin <path>] [--session <name>] [--reuse] [--cols <n>]"
description: "Entrypoint de FleetView: abre una ventana de terminal con una sesion tmux (socket aislado por perfil) de dos panes (TUI fleetview a la izquierda, claude --dangerously-skip-permissions a la derecha) para centralizar la flota de Claudes. La terminal se AUTO-DETECTA sin config por PC: kitty si esta instalado y hay display ($DISPLAY/$WAYLAND_DISPLAY), si no Windows Terminal (wt.exe) en WSL adjuntando via wsl.exe. El pane de la TUI corre dentro del bucle supervisor supervise_fleetview_tui, que la relanza si muere (crash/panic/kill), asi el panel de control NUNCA se pierde. Soporta PERFILES multiples: sin --session/--reuse cada invocacion abre un perfil nuevo (fleet, fleet2, fleet3, ...) con su propia flota; inyecta FLEET_SOCKET/FLEET_SESSION a la TUI para que cada panel vea solo sus Claudes. Instala atajos alt+flechas/alt+enter/alt+n que controlan la TUI desde cualquier pane, y fija el ancho del sidebar con hooks."
tags: [claude-fleet, infra, kitty, tmux, claude, fleetview, launcher, wsl, windows-terminal]
params:
  - name: --cwd
    desc: "Directorio de trabajo de ambos panes tmux. Opcional. Default: raiz del repo fn_registry, derivada dinamicamente via git rev-parse desde la ubicacion del script (sin hardcodear paths de usuario)."
  - name: --bin
    desc: "Ruta al binario de la TUI fleetview que corre en el pane izquierdo. Opcional. Default: <repo>/apps/fleetview/fleetview. Si no es ejecutable, el pane izquierdo muestra un mensaje de como compilarla y deja una shell viva."
  - name: --session
    desc: "Fija el perfil (socket+sesion tmux comparten nombre) por nombre exacto; reutiliza el existente si ya vive (idempotente sobre ese nombre). Opcional. Sin esta opcion, el perfil se elige automaticamente (primer nombre libre de la secuencia fleet, fleet2, ...)."
  - name: --reuse
    desc: "Reattach al perfil principal 'fleet' en vez de abrir uno nuevo. Opcional. Recupera el comportamiento idempotente clasico (volver a invocar NO duplica la flota, reusa la existente)."
  - name: --cols
    desc: "Ancho en columnas del pane izquierdo (la TUI). Opcional. Default: 40."
output: "Crea/reutiliza una sesion tmux detached con dos panes y lanza una ventana de terminal 'FleetView' adjunta a ella (kitty o Windows Terminal segun auto-deteccion), desacoplada del shell padre. Imprime el estado por stdout. Sin valor de retorno; exit 0 en exito."
uses_functions:
  - supervise_fleetview_tui_bash_infra
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
tested: false
tests: []
test_file_path: ""
file_path: "bash/functions/infra/launch_fleetclaude.sh"
---

## Ejemplo

```bash
# Via fn run (resuelve por nombre o ID):
fn run launch_fleetclaude

# Perfil nuevo automatico (fleet la 1a vez; fleet2, fleet3, ... si ya hay uno):
launch_fleetclaude

# Reattach a la flota principal 'fleet' (comportamiento idempotente clasico):
launch_fleetclaude --reuse

# Perfil con nombre fijo y ancho de pane personalizado:
launch_fleetclaude --session trabajo --cols 50
```

Tras invocarlo aparece una ventana de terminal titulada `FleetView (<perfil>)` con dos
panes lado a lado: a la izquierda la TUI `fleetview`, a la derecha una sesion de
`claude --dangerously-skip-permissions`. Cada perfil es un socket+sesion tmux
aislados con su propia flota: puedes tener varias FleetView abiertas a la vez.
Por defecto, volver a invocarlo abre un perfil NUEVO (no reusa); usa `--reuse`
o `--session <nombre>` para volver a una flota concreta.

## Cuando usarla

Usala cuando quieras un unico punto de entrada a la flota de Claudes en vez de
N ventanas kitty sueltas: lanzas `fleetclaude` y tienes la TUI de control y un
Claude listo para trabajar en la misma ventana. Tipico al empezar la jornada o
al retomar el trabajo en el repo `fn_registry`.

## Gotchas

- **Perfiles multiples (default = perfil nuevo)**: sin `--session` ni `--reuse`,
  cada invocacion abre un perfil NUEVO usando el primer nombre libre de la
  secuencia `fleet`, `fleet2`, `fleet3`, ... (socket+sesion tmux comparten el
  nombre del perfil). Asi puedes tener varias FleetView abiertas a la vez, cada
  una con su flota independiente. Un perfil cerrado libera su nombre: tras matar
  `fleet`, el siguiente lanzamiento vuelve a `fleet`. Para reattach a una flota
  concreta: `--reuse` (principal `fleet`) o `--session <nombre>` (idempotente
  sobre ese nombre, reusa el layout si ya vive).
- **Perfil ↔ TUI por entorno**: el launcher inyecta `FLEET_SOCKET`/`FLEET_SESSION`
  al pane de la TUI (y los fija en el server con `set-environment -g`, para que
  `respawn-pane` de alt+R y los Claude nuevos hereden el socket). `main.go` los
  lee con fallback a `fleet`. Por eso cada panel ve SOLO los Claude de su perfil
  (cruza la lista del sistema con los panes de su socket).
- **Auto-deteccion de terminal (sin config por PC)**: en la ruta ventana-nueva el
  launcher elige terminal solo. (1) `kitty` instalado **y** display usable
  (`$DISPLAY`/`$WAYLAND_DISPLAY`) → kitty (escritorio Linux nativo o WSLg con
  kitty). (2) Si no, WSL con `wt.exe` en el PATH → Windows Terminal ejecutando
  `wsl.exe [-d $WSL_DISTRO_NAME] -- bash -lic 'tmux -L <perfil> attach ...'`.
  (3) Ninguna → error con las salidas posibles. Asi el MISMO `fleetclaude`
  funciona en un PC con kitty y en otro WSL sin kitty, cada uno elige su
  terminal. Causa raiz del sintoma "se lanza la flota pero no se ve": kitty no
  instalado en WSL hacia que la sesion tmux se creara sin ventana que la mostrara.
- **Dentro de tmux abre ventana nueva**: si invocas `fleetclaude` desde dentro de
  una sesion tmux (`$TMUX` definido), NO hace `attach` anidado (rompe / avisa de
  nesting); cae a la ruta ventana-nueva (auto-deteccion de terminal). Fuera de
  tmux y con TTY, reutiliza la terminal actual con `exec tmux attach`.
- **kitty detached (setsid)**: la ventana kitty se lanza con `setsid ... &` para
  sobrevivir al cierre de la terminal que la invoco. La ventana de Windows
  Terminal (wt.exe) ya es un proceso Windows independiente del arbol Linux, asi
  que sobrevive sola (se lanza con `&`+`disown` desde un subshell con cwd `/mnt/c`
  para evitar el warning de wt.exe por cwd UNC `\\wsl.localhost\...`).
- **TUI bajo supervisor (auto-respawn)**: el pane izquierdo NO corre un
  `exec fleetview` de una sola vida, sino `supervise_fleetview_tui` (bucle que
  relanza la TUI si muere por crash/panic/kill). Asi el panel de control nunca se
  pierde por un fallo puntual. El supervisor para limpio con su sentinel
  (`touch ~/.claude/fleet/tui_stop_<perfil>` y deja salir la TUI) o se rinde si la
  TUI entra en crash-loop; en ambos casos el pane cae a una shell viva (no se
  cierra solo) para inspeccionar. Es la mitad "auto-recuperacion" del par de
  fixes que blindan FleetView; la otra es el Guard 3 anti-TUI/console de
  `kill_fleet_agent` (la causa raiz del cierre accidental). Si el script del
  supervisor no estuviera en disco, cae al `exec fleetview` clasico.
- **`exec` en los demas panes**: `claude` (orquestador e idle) se lanza con
  `exec`, asi que al terminar el proceso el pane se cierra en vez de dejar una
  shell zombie. Excepcion: el fallback cuando `fleetview` no esta compilado deja
  una shell interactiva a proposito (para que veas el mensaje y puedas compilar).
- **Requiere fleetview compilado**: el default `--bin` apunta a
  `<repo>/apps/fleetview/fleetview`. Si ese binario no existe, el pane izquierdo
  muestra `cd apps/fleetview && go build -o fleetview .` en lugar de fallar en
  silencio. Compila la TUI antes para el flujo completo.
- **Socket tmux aislado por perfil (`-L <perfil>`)**: cada perfil vive en su
  propio server tmux (socket = nombre del perfil), separado del tmux por defecto
  del usuario y de los demas perfiles. Asi los atajos `bind -n` NO afectan otras
  sesiones (ej. una sesion `mobile-1` del movil) y matar un perfil no toca los
  otros: `tmux -L <perfil> kill-server` (o `alt+q` dentro de la TUI).
- **Atajos en el socket, NO en kitty.conf**: instala `bind -n` para
  `alt+flechas` (mover el cursor de la TUI), `alt+enter` (conmutar al Claude
  seleccionado) y `alt+n` (abrir Claude nuevo). Son bindings de tmux que
  redirigen la tecla al pane de la TUI (`send-keys -t console.0`), asi funcionan
  ESTES DONDE ESTES (incluido escribiendo en el pane de Claude). No modifican la
  configuracion de kitty ni los atajos globales del escritorio.
- **Ancho del sidebar via hooks**: `client-resized` y `window-layout-changed`
  re-fijan el pane 0 (TUI) a `--cols` columnas, porque el `attach` de kitty y el
  conmutar de Claude redistribuyen el espacio.
- **tmux siempre; terminal (kitty/wt.exe) solo sin TTY**: `tmux` es obligatorio
  (aborta != 0 si falta). Una terminal nueva (kitty o Windows Terminal) solo se
  necesita en la ruta sin-TTY (dentro de tmux, atajo de escritorio, cron, script),
  donde abre una ventana nueva. Invocado desde una terminal interactiva fuera de
  tmux (el caso normal del alias `fleetclaude`), reutiliza la terminal actual con
  `exec tmux attach` y no necesita ni kitty ni wt.exe.

## Capability growth log

- v1.6.0 (2026-06-29) — **auto-deteccion de terminal (kitty ↔ Windows Terminal)**.
  La ruta ventana-nueva ya no asume kitty: elige terminal segun el host. kitty si
  esta instalado y hay display (`$DISPLAY`/`$WAYLAND_DISPLAY`); si no, en WSL abre
  Windows Terminal (`wt.exe`) ejecutando `wsl.exe [-d $WSL_DISTRO_NAME] -- bash
  -lic 'tmux ... attach'`. Mismo `fleetclaude` en un PC con kitty y en otro WSL
  sin kitty. Arregla el sintoma "se lanza la flota pero no se ve": en WSL sin
  kitty la sesion tmux se creaba pero ninguna ventana la mostraba. wt.exe se
  lanza desde un subshell con cwd `/mnt/c` para evitar el warning por cwd UNC.
- v1.5.0 (2026-06-24) — **auto-respawn de la TUI**. El pane izquierdo ya no corre
  `exec fleetview` (una sola vida), sino el bucle supervisor
  `supervise_fleetview_tui`, que relanza la TUI si muere (crash/panic/kill de su
  proceso o pane). Asi el panel de control NUNCA se pierde por un fallo puntual.
  Parada voluntaria via sentinel; crash-loop guard para no relanzar en bucle
  cerrado. Complementa el Guard 3 anti-TUI/console de `kill_fleet_agent` (causa
  raiz del cierre accidental). Nueva dependencia: `supervise_fleetview_tui_bash_infra`.
- v1.4.0 (2026-06-18) — **perfiles multiples**. Socket+sesion tmux ya no son el
  fijo `fleet`: cada perfil tiene los suyos (mismo nombre). Sin `--session`/
  `--reuse`, cada invocacion abre el primer perfil libre (`fleet`, `fleet2`, ...),
  asi abrir FleetView con uno ya abierto arranca otra flota en vez de reusarla.
  Nuevo flag `--reuse` para el reattach idempotente clasico. El launcher inyecta
  `FLEET_SOCKET`/`FLEET_SESSION` (env + `set-environment -g`) y `main.go` de
  `fleetview` los lee (fallback `fleet`), de modo que cada panel ve solo su flota.
  Titulo de kitty `FleetView (<perfil>)`. Guard anti-nesting: invocado dentro de
  tmux abre ventana kitty nueva en vez de `attach` anidado.
- v1.3.2 (2026-06-17) — targeting de panes por **pane ID** (`%0`/`%1`) en vez de
  por indice (`console.0`). Antes fallaba con `can't find pane: 0` en hosts cuyo
  `~/.tmux.conf` define `base-index 1`/`pane-base-index 1` (el socket `-L fleet`
  hereda esa config). Los pane ID son inmunes al base-index. Bug latente que el
  fix de kitty (v1.3.1) destapo al dejar de abortar antes de montar la sesion.
- v1.3.1 (2026-06-17) — el guard de `kitty` se movio a la rama sin-TTY. La ruta
  interactiva (`exec tmux attach`) ya no exige kitty, asi que `fleetclaude`
  funciona en hosts sin kitty (p.ej. WSL) reutilizando la terminal actual.
- v1.3.0 (2026-06-17) — renombrada de `launch_kittyclaude` a `launch_fleetclaude`
  (comando `fleetclaude`). Atajos: `alt+0` (= alt+n, abrir Claude nuevo), `alt+k`
  (kill con confirmacion), `alt+r` (picker de reanudar sesiones cerradas) y
  `alt+flecha-izquierda` (volver atras desde el picker). Cierra la window al salir
  el Claude (`remain-on-exit off`).
- v1.2.0 (2026-06-16) — ancho del sidebar por defecto 47 columnas; `ctrl+0` como
  atajo alterno para abrir Claude nuevo; `mouse on` (clic/rueda enrutados a la
  TUI) y `extended-keys on` (para que `ctrl+0` llegue distinguible por el
  protocolo de teclado de kitty).
- v1.1.0 (2026-06-16) — socket tmux aislado `-L fleet`; instala atajos
  `alt+flechas` / `alt+enter` / `alt+n` que controlan la TUI desde cualquier
  pane; hooks que mantienen fijo el ancho del sidebar tras attach/conmutar.