145 lines
9.0 KiB
Markdown
145 lines
9.0 KiB
Markdown
---
|
|
name: launch_fleetclaude
|
|
kind: function
|
|
lang: bash
|
|
domain: infra
|
|
version: "1.4.0"
|
|
purity: impure
|
|
signature: "launch_fleetclaude [--cwd <dir>] [--bin <path>] [--session <name>] [--reuse] [--cols <n>]"
|
|
description: "Entrypoint de FleetView: abre una ventana kitty 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. 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]
|
|
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 kitty 'FleetView' adjunta a ella, desacoplada del shell padre (setsid). Imprime el estado por stdout. Sin valor de retorno; exit 0 en exito."
|
|
uses_functions: []
|
|
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 kitty 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).
|
|
- **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 kitty y abre una ventana nueva. Fuera de tmux y con
|
|
TTY, reutiliza la terminal actual con `exec tmux attach`.
|
|
- **kitty detached (setsid)**: la ventana se lanza con `setsid ... &` para
|
|
sobrevivir al cierre de la terminal que la invoco. No bloquea al shell padre.
|
|
- **`exec` en los panes**: tanto la TUI como `claude` se lanzan con `exec`, asi
|
|
que al terminar el proceso el pane se cierra en vez de dejar una shell zombie
|
|
colgando. 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, kitty solo sin TTY**: `tmux` es obligatorio (aborta != 0 si
|
|
falta). `kitty` solo se necesita en la ruta sin-TTY (atajo de escritorio, cron,
|
|
script), donde abre una ventana nueva. Invocado desde una terminal interactiva
|
|
(el caso normal del alias `fleetclaude`), reutiliza la terminal actual con
|
|
`exec tmux attach` y NO necesita kitty — util en WSL u hosts sin kitty.
|
|
|
|
## Capability growth log
|
|
|
|
- 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.
|