# CCB - O app móvel chegou!
**Um TUI multiagente leve com uma camada estável de colaboração entre providers**
**Coordene Codex, Claude, Gemini e outros agentes CLI em fluxos visíveis e controláveis que você pode assumir diretamente**
## Por que CCB?
- Comunicação estável entre agentes para grafos complexos como `A -> B -> C`, `A,B -> C` e `A -> B,C`.
- Cada agente é um terminal nativo completo, com controle visível de layout e intervenção direta.
- O daemon em segundo plano mantém o estado do projeto mesmo quando a UI de primeiro plano é fechada.
- Capacidade Hub: execute vários CLI providers em paralelo a partir de um único comando.
- Controle remoto móvel: controle por voz entre providers, transferência de arquivos e acesso a terminal remoto.
## Como instalar
Instale ou atualize uma instalação gerenciada pelo npm com npm:
```bash
npm install -g @seemseam/ccb@latest
```
Para instalações via GitHub release ou fonte, use o updater transacional do CCB:
```bash
ccb update
```
Em uma instalação gerenciada pelo npm, `ccb update` mostra o comando npm equivalente sem modificar o payload incluído.
Pacote GitHub release e instalação por fonte como fallback
Se npm não for conveniente no seu ambiente, baixe o pacote adequado em [Releases](https://github.com/SeemSeam/claude_codex_bridge/releases), descompacte e instale:
```bash
tar -xzf ccb-*.tar.gz
cd ccb-*
./install.sh install
```
A instalação por fonte é indicada apenas para desenvolvimento ou fallback temporário:
```bash
git clone https://github.com/SeemSeam/claude_codex_bridge.git
cd claude_codex_bridge
./install.sh install
```
A instalação por fonte aponta os comandos globais `ccb` / `ask` de volta para o checkout. Usuários comuns devem preferir o pacote npm.
## Início rápido
### 1. Iniciar
Execute a partir do seu diretório de trabalho:
```bash
ccb
```
Se a inicialização informar que `.ccb` não pode ser criado automaticamente ou que a âncora do projeto está ausente, crie `.ccb` manualmente:
```bash
mkdir -p .ccb
```
### 2. Criar configuração do projeto
Um projeto vazio inicia de forma leve: o CCB abre apenas uma window `main` com um agent chamado `demo` e seleciona o primeiro CLI compatível disponível na máquina. Uma equipe multiagente não é mais montada por padrão.
Clique em **⚙ Configurações** no canto superior esquerdo da sidebar do CCB para abrir o painel de configuração local. Você também pode executar `ccb config ui`.
O painel configura windows, divisões de panes, providers, modelos, níveis de thinking, API overrides, workspaces, modo Rich e sidebar. Ele valida antes de salvar e oferece reload dry-run e hot reload protegido.
Para uma topologia multiagente avançada, adicione agents visualmente ou crie `.ccb/ccb.config` manualmente. `,` e `;` controlam empilhamento vertical e divisões horizontais; `A,B;C,D` se aproxima de quatro 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
```
Valide a configuração e inicie o workspace:
```bash
ccb config validate
ccb
```
### 3. Colaborar
Você pode digitar diretamente em qualquer agent pane ou deixar os agentes colaborarem:
```text
/ask reviewer review the latest parser changes and list blocking issues.
```
Agentes também podem chamar `/ask` durante a orquestração de workflows para delegar e passar trabalho adiante. Use a memória de agent ou o arquivo compartilhado do projeto `.ccb/ccb_memory.md` para coordenação durável.
## Controle remoto móvel (Android)
A forma recomendada de controlar o CCB pelo telefone pode conectar-se a todos os projetos CCB, controlar cada agent, aceitar entrada por voz e transferir arquivos.
```bash
ccb update mobile
```
Esse comando orienta a instalação e a configuração.
Detalhes do Mobile App, limite de segurança e fonte
O CCB 8.5.2 inclui o código Flutter do CCB Mobile em [`mobile/`](../mobile/) e publica o APK Android pelo GitHub Releases:
- [Baixar CCB Mobile v8.5.2 APK](https://github.com/SeemSeam/claude_codex_bridge/releases/download/v8.5.2/ccb-mobile-v8.5.2.apk)
- Fonte do app: [`mobile/app`](../mobile/app)
- Fonte do gateway servidor: [`lib/mobile_gateway`](../lib/mobile_gateway)
O app do telefone é um controlador remoto para projetos CCB reais rodando em um servidor. Ele pode descobrir projetos montados pelo mobile gateway server-wide, trocar windows e agents, renderizar contexto de conversa, enviar texto via entrada pane-native, abrir uma visão terminal e enviar/baixar imagens e documentos pelo gateway autenticado.
Limite de segurança:
- O gateway CCB faz bind apenas em loopback, por exemplo `127.0.0.1:8787`.
- O acesso remoto usa Tailscale Serve, não Tailscale Funnel.
- O CCB não armazena senhas Tailscale, OAuth tokens, admin API tokens, nem modifica ACLs/grants do tailnet automaticamente.
- O telefone recebe apenas os scopes autorizados pelo pairing profile, como view, content, terminal, file upload e file download.
## Terminal multimídia Rich
Explore árvores de arquivos, abra arquivos, edite documentos e visualize mídia dentro do terminal.
```bash
ccb update rich
```
Depois que rich mode é ativado, `ccb` normal abre automaticamente o rich WezTerm launcher, a menos que já esteja rodando dentro de uma sessão rich WezTerm gerenciada pelo CCB. Execute `ccb uninstall rich` para voltar ao início normal no terminal.
## Agent Roles Spec e catálogo de roles
O CCB suporta [Agent Roles Spec](https://github.com/SeemSeam/agent-roles-spec), uma especificação host-neutral para empacotar agentes especialistas. Ela pode agrupar skills, memória e dependências de ferramentas em Role Packs instaláveis, montáveis e removíveis. Esse repositório também serve como catálogo público de roles.
| Role | Propósito |
| :--- | :--- |
| `agentroles.ccb_self` | Automanutenção do CCB, ajuda de configuração, diagnóstico runtime, recuperação protegida e orquestração de workflow. |
| `agentroles.archi` | Revisão de arquitetura, checagem de limites, análise de acoplamento, riscos de manutenção e recomendações de gates. |
| `agentroles.frontend_engineer` | Design e implementação frontend, design systems, acessibilidade, QA de navegador e delegação AGY revisada. |
| `agentroles.mobile_app_engineer` | Design e implementação mobile para iOS, Android, React Native, Expo, Flutter, SwiftUI, Jetpack Compose e mais. |
| `agentroles.mother` | Criação de roles, auditoria de role source, pesquisa de roles, design de blueprint e checagens de conformidade Agent Roles. |
| `agentroles.su_ccb` | Operações workflow SU-CCB para análise de requisitos, planejamento, dispatch, review gates, arquivamento e recuperação. |
## Configuração e memória compartilhada
Para a configuração normal do projeto, use o painel **⚙ Configurações**. Para configuração assistida por agent e diagnóstico runtime, `ccb_self` continua disponível como Role Pack opcional e pode ser adicionado com `ccb roles add agentroles.ccb_self:codex`.
`.ccb/ccb_memory.md` é o documento de memória compartilhada de todo o projeto. Use-o para regras de colaboração da equipe, restrições do projeto, contexto durável e convenções de handoff entre agents. Informações estáveis entre agents devem ficar ali, em vez de serem copiadas para várias memórias privadas de providers.
## Contato
- Email: `bfly123@126.com`
- [Telegram group & contact / TG 群与联系](https://t.me/+BKn03v8I_ehmYzRk)
- WeChat: `seemseam-com`
## Comunidade e créditos
Obrigado à [comunidade Linux.do](https://linux.do) pelos testes, feedback e discussão.
Obrigado ao [tmux-agent-sidebar](https://github.com/hiroppy/tmux-agent-sidebar) pelas ideias e inspiração de sidebar.
## Notas de versão
v8.4.0 - Relay móvel criptografado, pareamento simples, identidade estável e reconexão Codex
- Adiciona Relay móvel com criptografia ponta a ponta, convites de uso único, streams multiplexados e modos oficial ou auto-hospedado.
- Move a escolha de Tailscale, LAN privada ou Relay para `ccb update mobile`; o telefone apenas lê o QR ou informa um código.
- Verifica metadados oficiais do GitHub, tamanho e SHA-256 antes de entregar uma atualização APK assinada ao Android.
- Preserva a identidade após mover projetos, acompanha o tema do sistema e integra a reconexão opcional e limitada do Codex.
v8.3.1 - Atualizações de providers unificadas, retirada segura de caches e acesso persistente à Config UI
- Centraliza upgrades de providers suportados em `ccb update`, com verificação exata, recusa e salto por versão, sem reiniciar panes ativos.
- Retira caches de software Claude/Gemini por projeto e limpa apenas dados legados com propriedade comprovada; projetos ativos, sessões e autenticação são preservados.
- Permite uma porta loopback estável e uma fonte de token protegida para a Config UI sem exibir o valor do token.
- Preserva finalizadores de shutdown durante a parada do servidor e adota um layout Yazi compacto de duas colunas no Rich mode.
- Sincroniza CLI, npm, Linux, macOS, Android e todos os artefatos de release com 8.3.1.
v8.3.0 - Turnos exatos dos providers, integridade dos jobs e terminal Mobile dentro do projeto
- Vincula Kimi, Claude e Qoder aos contratos nativos de turno, ativação, sessão e conclusão.
- Adiciona follow-ups para o job ativo exato, fases de execução correlacionadas, diagnóstico de inbounds órfãos e cancelamento terminal.
- Herda extensões de providers e plugins do Copilot com proteção explícita de ownership dos assets projetados.
- Delega upgrades gerenciados por npm ao próprio npm e torna conservadora a remoção de worktrees que contêm apenas marcadores.
- Mantém chat e terminal Mobile no workspace do projeto selecionado e sincroniza todas as superfícies de release com 8.3.0.
v8.2.1 - Inicialização determinística, recuperação de autenticação acionável e conexão Android em segundo plano
- Adiciona cercas de geração de inicialização, prova limitada de prontidão e diagnósticos de operações e linha do tempo.
- Interrompe ciclos de reinício sem saída por autenticação do provider e mostra a ação de login necessária.
- Adiciona conexão Android em segundo plano opcional e um único estado de resposta ativa por Agent.
- Sincroniza os artefatos Linux, macOS, npm e Android assinado com 8.2.1.
v8.2.0 - Inicialização mais rápida, correções de providers e Mobile confiável
- Reduz trabalho repetido na inicialização do ccbd sem enfraquecer verificações de lifecycle e ownership.
- Corrige o fullscreen do Grok, preserva o tipo de credencial Claude, estabiliza escolhas de model/thinking e reforça a entrega ask/reply do Codex.
- Melhora recovery, chat, terminal, anexos, downloads e FCM no Mobile; sincroniza artifacts Linux, macOS, npm e Android assinado com 8.2.0.
v8.0.14 - Organização do diretório README e superfície mobile
- O `README.md` raiz voltou a ser a página GitHub em inglês.
- READMEs localizados agora ficam em [`README/`](./), com chinês em [`zh.md`](zh.md).
- Links do Mobile App, package metadata e release notes apontam para o APK 8.0.14.
v8.0.12 - Portabilidade do Release CI e localização do README
- Testes mobile host registry agora colocam Unix sockets temporários em um caminho curto `/tmp/ccb-sock-*`, evitando falhas `AF_UNIX path too long` no macOS CI.
- `ccb update mobile`, links do README, package metadata e o mobile release manifest agora apontam para o APK 8.0.12.
- O v8.0.12 introduziu READMEs multilíngues com a mesma estrutura de seções; os arquivos localizados atuais ficam no diretório `README/`.
v8.0.0 - Lançamento do CCB Mobile Monorepo
- O código Flutter do CCB Mobile entrou oficialmente neste repositório, com o APK Android publicado via GitHub Releases.
- Foram adicionados descoberta server-wide de projetos mobile, pairing, rotas gateway autenticadas, entrada pane-native, renderização de contexto de conversa, acesso terminal e upload/download de imagens e documentos.
- `ccb update mobile` virou o ponto de entrada unificado de onboarding Tailscale Tailnet, mantendo o gateway loopback-only, sem Funnel, sem armazenar tokens e sem modificar ACLs/grants automaticamente.
v7.7.0 - Endurecimento de release do Runtime Accelerator
- Os release artifacts agora incluem o Rust `ccb-runtime-accelerator` opcional; agents Codex instalados não retornam silenciosamente ao Python hot path quando o sidecar é esperado.
- Quando o caminho do projeto torna o Unix socket path longo demais, o accelerator socket migra automaticamente para uma raiz runtime curta por usuário.
- Callback repair e invalidação do cache de binding Codex foram reforçados, com evidências de regressão, long-idle Codex soak, callback Claude e integração mixed-provider.
v7.6.19 - Política padrão de espera para ask longo
- Chamadas `ask` longas agora continuam aguardando resultados reais de provider/completion, em vez de terminar como `incomplete/heartbeat_timeout` apenas por diagnósticos heartbeat.
- No-terminal timeouts pane-backed de Codex, Claude e Gemini agora são opt-in explícito por padrão, mantendo disponíveis políticas explícitas de reliability timeout.
- Um smoke source-runtime ask de 32 minutos confirmou que uma tarefa pode permanecer running por mais de 30 minutos e depois concluir com `result_message`, sem evidência de `heartbeat_timeout` ou `incomplete`.
Veja o histórico completo em [CHANGELOG.md](../CHANGELOG.md).
