# CCB - ¡La app móvil ya llegó!
**Un TUI multiagente ligero con una capa estable de colaboración entre proveedores**
**Coordina Codex, Claude, Gemini y otros agentes CLI en flujos visibles y controlables que puedes tomar directamente**
## ¿Por qué CCB?
- Comunicación estable entre agentes para grafos complejos como `A -> B -> C`, `A,B -> C` y `A -> B,C`.
- Cada agente es una terminal nativa completa, con control visible del diseño y toma directa.
- El daemon en segundo plano conserva el estado del proyecto aunque se cierre la interfaz frontal.
- Capacidad Hub: ejecutar varios CLI providers en paralelo desde un solo comando.
- Controlador móvil remoto: control por voz entre providers, transferencia de archivos y acceso a terminal remoto.
## Cómo instalar
Instala o actualiza una instalación administrada por npm con npm:
```bash
npm install -g @seemseam/ccb@latest
```
Para instalaciones desde GitHub release o fuente, usa el updater transaccional de CCB:
```bash
ccb update
```
En una instalación administrada por npm, `ccb update` muestra el comando npm equivalente sin modificar el payload incluido.
Paquete de GitHub release e instalación desde fuente como respaldo
Si npm no es conveniente en tu entorno, descarga el paquete adecuado desde [Releases](https://github.com/SeemSeam/claude_codex_bridge/releases), descomprímelo e instálalo:
```bash
tar -xzf ccb-*.tar.gz
cd ccb-*
./install.sh install
```
La instalación desde fuente está pensada solo para desarrollo o respaldo temporal:
```bash
git clone https://github.com/SeemSeam/claude_codex_bridge.git
cd claude_codex_bridge
./install.sh install
```
La instalación desde fuente enlaza los comandos globales `ccb` / `ask` al checkout actual. Los usuarios normales deberían preferir el paquete npm.
## Inicio rápido
### 1. Iniciar
Ejecuta esto desde tu directorio de trabajo:
```bash
ccb
```
Si el arranque indica que `.ccb` no puede crearse automáticamente o que falta el ancla del proyecto, créala manualmente:
```bash
mkdir -p .ccb
```
### 2. Crear la configuración del proyecto
Un proyecto vacío arranca de forma ligera: CCB abre una sola window `main` con un agente llamado `demo` y selecciona el primer CLI compatible disponible en el equipo. Ya no monta un equipo multiagente por defecto.
Haz clic en **⚙ Configuración** en la esquina superior izquierda de la sidebar de CCB para abrir el panel de configuración local. También puedes ejecutar `ccb config ui`.
El panel configura windows, divisiones de panes, providers, modelos, niveles de thinking, API overrides, workspaces, modo Rich y sidebar. Valida antes de guardar y admite reload dry-run y hot reload protegido.
Para una topología multiagente avanzada, añade agentes visualmente o crea `.ccb/ccb.config` manualmente. `,` y `;` controlan el apilamiento vertical y las divisiones horizontales; `A,B;C,D` se aproxima a cuatro panes.
```toml
version = 2
[windows]
main = "main:codex"
work = "worker1:codex(worktree), worker2:claude(worktree)"
review = "reviewer:claude, qa:gemini"
[ui.sidebar]
mode = "every_window"
width = "15%"
bottom_height = 20
agents_height = "50%"
comms_height = "15%"
tips_height = "35%"
comms_limit = 3
```
Valida la configuración e inicia el espacio de trabajo:
```bash
ccb config validate
ccb
```
### 3. Colaborar
Puedes escribir directamente en cualquier agent pane o hacer que los agentes colaboren:
```text
/ask reviewer review the latest parser changes and list blocking issues.
```
Los agentes también pueden llamar a `/ask` durante la orquestación de workflows para delegar y entregar trabajo. Usa la memoria de agente o el archivo compartido del proyecto `.ccb/ccb_memory.md` para coordinación duradera.
## Control remoto móvil (Android)
La forma recomendada de controlar CCB desde un teléfono puede conectarse a todos los proyectos CCB, controlar cada agente, aceptar entrada de voz y transferir archivos.
```bash
ccb update mobile
```
Este comando guía la instalación y configuración.
Detalles de Mobile App, límite de seguridad y fuente
CCB 8.5.2 incluye el código Flutter de CCB Mobile en [`mobile/`](../mobile/) y publica el APK Android mediante GitHub Releases:
- [Descargar CCB Mobile v8.5.2 APK](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.5.2/ccb-mobile-v8.5.2.apk)
- Fuente de la app: [`mobile/app`](../mobile/app)
- Fuente del gateway del servidor: [`lib/mobile_gateway`](../lib/mobile_gateway)
La app del teléfono es un controlador remoto para proyectos CCB reales que corren en un servidor. Puede descubrir proyectos montados desde el mobile gateway server-wide, cambiar windows y agents, renderizar contexto de conversación, enviar texto por entrada pane-native, abrir vista terminal y subir/descargar imágenes y documentos por el gateway autenticado.
Límite de seguridad:
- El gateway CCB solo se enlaza a loopback, por ejemplo `127.0.0.1:8787`.
- El acceso remoto usa Tailscale Serve, no Tailscale Funnel.
- CCB no guarda contraseñas de Tailscale, OAuth tokens, admin API tokens, ni modifica automáticamente ACLs/grants del tailnet.
- El teléfono recibe solo los scopes autorizados por el pairing profile, como view, content, terminal, file upload y file download.
## Terminal multimedia Rich
Explora árboles de archivos, abre archivos, edita documentos y previsualiza medios dentro de la terminal.
```bash
ccb update rich
```
Después de activar rich mode, `ccb` abre automáticamente el rich WezTerm launcher salvo que ya esté dentro de una sesión rich WezTerm gestionada por CCB. Ejecuta `ccb uninstall rich` para volver al inicio normal de terminal.
## Agent Roles Spec y catálogo de roles
CCB admite [Agent Roles Spec](https://github.com/SeemSeam/agent-roles-spec), una especificación host-neutral para empaquetar agentes especialistas. Puede agrupar skills, memoria y dependencias de herramientas en Role Packs instalables, montables y removibles. Ese repositorio también funciona como catálogo público de roles.
| Role | Propósito |
| :--- | :--- |
| `agentroles.ccb_self` | Automantenimiento de CCB, ayuda de configuración, diagnóstico runtime, recuperación protegida y orquestación de workflows. |
| `agentroles.archi` | Revisión de arquitectura, verificación de límites, análisis de acoplamiento, riesgos de mantenibilidad y recomendaciones de gates. |
| `agentroles.frontend_engineer` | Diseño e implementación frontend, design systems, accesibilidad, QA de navegador y delegación AGY revisada. |
| `agentroles.mobile_app_engineer` | Diseño e implementación móvil para iOS, Android, React Native, Expo, Flutter, SwiftUI, Jetpack Compose y más. |
| `agentroles.mother` | Creación de roles, auditoría de role source, investigación de roles, diseño de blueprints y controles de cumplimiento de Agent Roles. |
| `agentroles.su_ccb` | Operaciones workflow SU-CCB para análisis de requisitos, planificación, dispatch, review gates, archivado y recuperación. |
## Configuración y memoria compartida
Para la configuración normal del proyecto, usa el panel **⚙ Configuración**. Si quieres configuración asistida por un agente y diagnóstico runtime, `ccb_self` sigue disponible como Role Pack opcional y se añade con `ccb roles add agentroles.ccb_self:codex`.
`.ccb/ccb_memory.md` es el documento de memoria compartida de todo el proyecto. Úsalo para reglas de colaboración del equipo, restricciones del proyecto, contexto duradero y convenciones de entrega entre agentes. La información estable entre agentes debe vivir ahí en vez de copiarse en varias memorias privadas de providers.
## Contacto
- Email: `bfly123@126.com`
- [Telegram group & contact / TG 群与联系](https://t.me/+BKn03v8I_ehmYzRk)
- WeChat: `seemseam-com`
## Comunidad y créditos
Gracias a la [comunidad Linux.do](https://linux.do) por pruebas, comentarios y discusión.
Gracias a [tmux-agent-sidebar](https://github.com/hiroppy/tmux-agent-sidebar) por las ideas e inspiración de la sidebar.
## Notas de versión
v8.4.0 - Relay móvil cifrado, emparejamiento simple, identidad estable y reconexión Codex
- Añade Relay móvil cifrado de extremo a extremo, invitaciones de un solo uso, streams multiplexados y modos oficial o autohospedado.
- Traslada la selección de Tailscale, LAN privada o Relay a `ccb update mobile`; el teléfono solo escanea un QR o introduce un código.
- Verifica metadatos oficiales de GitHub, tamaño y SHA-256 antes de entregar una actualización APK firmada a Android.
- Conserva la identidad al mover proyectos, sigue el tema del sistema e integra la reconexión opcional de Codex con límites estrictos.
v8.3.1 - Actualizaciones unificadas de providers, retiro seguro de cachés y acceso persistente a Config UI
- Centraliza las actualizaciones compatibles de providers en `ccb update`, con comprobación exacta de versión, rechazo y omisión por versión, sin reiniciar panes activos.
- Retira las cachés de software Claude/Gemini por proyecto y limpia solo datos heredados cuya propiedad está verificada; conserva proyectos activos, sesiones y autenticación.
- Permite un puerto loopback estable y una fuente de token protegida para Config UI sin mostrar el valor del token.
- Conserva los finalizadores de shutdown mientras se detiene el servidor y adopta un diseño Yazi compacto de dos columnas en Rich mode.
- Sincroniza CLI, npm, Linux, macOS, Android y todos los artefactos de release con 8.3.1.
v8.3.0 - Turnos exactos de providers, integridad de jobs y terminal Mobile dentro del proyecto
- Vincula Kimi, Claude y Qoder a sus contratos nativos de turno, activación, sesión y finalización.
- Añade follow-ups para el job activo exacto, fases de ejecución correlacionadas, diagnóstico de inbounds huérfanos y cancelación terminal.
- Hereda extensiones de providers y plugins de Copilot con protección explícita de ownership para los assets proyectados.
- Delega las actualizaciones gestionadas por npm a npm y retira de forma conservadora los worktrees que solo contienen marcadores.
- Mantiene el chat y el terminal Mobile dentro del workspace del proyecto seleccionado y sincroniza todas las superficies de release con 8.3.0.
v8.2.1 - Inicio determinista, recuperación de autenticación accionable y conexión Android en segundo plano
- Añade cercas de generación de inicio, prueba acotada de disponibilidad y diagnósticos de operaciones y cronología.
- Detiene los reinicios sin salida por autenticación del provider y muestra la acción de inicio de sesión necesaria.
- Añade conexión Android en segundo plano opcional y un único estado de respuesta activa por Agent.
- Sincroniza los artefactos Linux, macOS, npm y Android firmado con 8.2.1.
v8.2.0 - Inicio más rápido, correcciones de providers y Mobile fiable
- Reduce trabajo repetido durante el inicio de ccbd sin debilitar las comprobaciones de lifecycle y ownership.
- Corrige el inicio fullscreen de Grok, conserva el tipo de credencial de Claude, estabiliza la selección de model/thinking y refuerza la entrega ask/reply de Codex.
- Mejora recovery, chat, terminal, adjuntos, descargas y FCM en Mobile; sincroniza los artefactos Linux, macOS, npm y Android firmado con 8.2.0.
v8.0.14 - Limpieza del directorio README y superficie mobile
- El `README.md` raíz vuelve a ser la portada GitHub en inglés.
- Los README localizados ahora viven en [`README/`](./), con chino en [`zh.md`](zh.md).
- Los enlaces de Mobile App, package metadata y release notes apuntan al APK 8.0.14.
v8.0.12 - Portabilidad de Release CI y localización del README
- Las pruebas mobile host registry ahora colocan sockets Unix temporales bajo una ruta corta `/tmp/ccb-sock-*`, evitando fallos `AF_UNIX path too long` en macOS CI.
- `ccb update mobile`, los enlaces del README, los metadatos del paquete y el mobile release manifest ahora apuntan al APK 8.0.12.
- v8.0.12 introdujo los README multilingues con una estructura de secciones compartida; los archivos localizados actuales viven en el directorio `README/`.
v8.0.0 - Publicación de CCB Mobile Monorepo
- El código Flutter de CCB Mobile entró oficialmente en este repositorio, con el APK Android publicado mediante GitHub Releases.
- Se agregó descubrimiento server-wide de proyectos móviles, pairing, rutas gateway autenticadas, entrada pane-native, renderizado de contexto de conversación, acceso terminal y subida/descarga de imágenes y documentos.
- `ccb update mobile` pasó a ser el punto de entrada unificado de onboarding de Tailscale Tailnet, manteniendo el gateway solo en loopback, sin Funnel, sin guardar tokens y sin modificar ACLs/grants automáticamente.
v7.7.0 - Endurecimiento de publicación de Runtime Accelerator
- Los release artifacts ahora incluyen el Rust `ccb-runtime-accelerator` opcional; los agentes Codex instalados ya no caen silenciosamente al Python hot path cuando se espera el sidecar.
- Cuando la ruta del proyecto hace demasiado larga la ruta Unix socket, el accelerator socket se mueve automáticamente a una raíz runtime corta por usuario.
- Se reforzó callback repair y la invalidación de cache de binding Codex, con evidencia de regresión, long-idle Codex soak, callback Claude e integración mixed-provider.
v7.6.19 - Política de espera predeterminada para ask largos
- Los `ask` largos normales siguen esperando resultados reales de provider/completion en vez de terminar como `incomplete/heartbeat_timeout` solo por diagnósticos heartbeat.
- Los no-terminal timeouts pane-backed de Codex, Claude y Gemini ahora son opt-in explícito por defecto, manteniendo disponibles las políticas explícitas de reliability timeout.
- Un smoke source-runtime ask de 32 minutos confirmó que una tarea puede permanecer running más de 30 minutos y luego completar con `result_message`, sin evidencia de `heartbeat_timeout` ni `incomplete`.
Consulta el historial completo en [CHANGELOG.md](../CHANGELOG.md).
