> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Web UI
> Uma app no navegador sobre o mesmo motor do terminal: chat, coder e agent com suas tools, skills, memória, sessões e canais, transmitidos ao vivo, com os diálogos de permissão dos loops respondidos na página. Aberta com /web ao lado do terminal ou servida com chatcli web.
`/web` abre o ChatCLI no seu navegador, ao lado do terminal, **na mesma sessão**. O que você escreve no navegador continua no terminal, no MCP, no ACP e nos seus canais, e vice-versa, porque o navegador aciona exatamente o mesmo motor e as mesmas sessões salvas que as outras superfícies acionam. `chatcli web` a serve sem terminal.
É local por construção: o servidor escuta na interface de loopback numa porta livre, cada execução cria o próprio token, o token viaja num header que a página lê do endereço uma vez, e nada sai da sua máquina.
***
## Abrindo
| Comando | O que faz |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `/web` | Sobe a web UI vinculada à sessão deste terminal e abre no navegador |
| `/web url` | Sobe e só imprime o endereço |
| `/web status` | Mostra se está rodando, o endereço, o processo filho e a sessão vinculada |
| `/web off` | Para |
| `chatcli web` | Serve a web UI de um terminal próprio, até `Ctrl+C`, vinculada a uma sessão `web-` nova |
| `chatcli web --session nome` | Serve vinculada a uma sessão salva |
| `chatcli web --addr 127.0.0.1:8765 --no-browser` | Porta fixa, só imprime o endereço |
`/web` funciona no meio de um turno, como o `/dash`. Um terminal que não está vinculado a uma sessão salva é vinculado a uma nova antes (`web-`), para a conversa ter um nome que as duas superfícies acompanhem; um terminal já vinculado compartilha a sessão como está. O navegador abre exatamente com o que essa sessão tem: rode `/web` no meio de uma conversa e a página começa com esses turnos e sincroniza dali; rode num terminal que ainda não digitou nada e a página começa vazia. Ela nunca é preenchida com o espelho rolling `mcp-web` de uma execução anterior. Fechar o terminal encerra a web UI: o endereço carregava um token que só aquele processo entregou.
`chatcli web` sozinho faz o mesmo: sem `--session` ele vincula o navegador a uma sessão `web-` nova, criada no primeiro turno concluído, então cada execução avulsa guarda a própria conversa em vez de sobrescrever o espelho rolling `mcp-web`. Nada é salvo "no fim": cada turno concluído é gravado assim que termina, então `Ctrl+C` ou fechar a aba perde no máximo um turno que ainda estava em streaming. Um terminal vinculado a uma sessão nomeada, inclusive a `web-` que o `/web` cria, é gravado uma última vez na saída e **não** é duplicado como arquivo `autosave-`.
O navegador só abre a partir de um terminal interativo. `chatcli web --no-browser`, ou um pipe, imprime o endereço.
## Continuidade entre superfícies
A web UI não é um segundo motor. Ela roda sobre o backend RPC compartilhado em que o [servidor MCP](/pt/features/mcp-server), o [servidor ACP](/pt/features/acp) e o [chat gateway](/pt/features/chat-gateway) rodam, e mantém a sessão do mesmo jeito:
* o histórico ao vivo do navegador é **vinculado** a uma sessão salva e gravado após cada turno;
* antes de cada turno a sessão vinculada é relida quando outra superfície a mudou (o terminal, uma IDE por ACP, uma conversa de WhatsApp ou Telegram pelo gateway), então uma resposta dada em outro lugar já está na transcrição antes de você continuar;
* a thread do [Conversation Hub](/pt/features/conversation-hub) do principal é retomada, exatamente como o `chatcli mcp-server` faz.
A barra lateral lista todas as sessões salvas com título. Vincule uma para continuá-la, bifurque, ou comece uma nova. **+ Nova** limpa a página e a vincula a uma sessão `web-` própria (o arquivo aparece no primeiro turno), então a conversa nova é salva e listada como qualquer outra; o terminal segue na sessão que tinha, e o cabeçalho mostra a sessão à qual a página está vinculada. Apagar é o mesmo `/session delete` que o terminal executa.
## O que você vê
| Área | O que contém |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cabeçalho** | Modo (Chat, Coder, Agent), seletores de provider e modelo preenchidos pelo catálogo e pelas listas ao vivo, o custo da sessão, alternadores de tema e idioma, o botão do painel |
| **Sessões** | Sessões salvas com título e idade, busca, nova, bifurcar, apagar |
| **Transcrição** | Respostas transmitidas renderizadas como Markdown (títulos, listas, tabelas, blocos de código com copiar), blocos de raciocínio, cartões de tools com entrada e saída, o plano do agent, avisos de cancelamento e erro |
| **Compositor** | Enter envia, Shift+Enter quebra a linha, `/` abre a paleta de comandos, `@` a de tools; imagens por arquivo ou colagem; entrada de voz e geração de imagem quando configuradas |
| **Painel** | Status (rota, política, max tokens, custo, orçamento diário), Tools, Skills, servidores MCP, recursos de memória, comandos |
### Modos e permissões
Turnos de chat transmitem token a token pelo caminho de streaming do provider. Turnos de coder e agent transmitem os eventos estruturados do loop: raciocínios, mensagens, cada chamada de tool ao começar e terminar, e o plano. Quando um loop chega a uma ação sob política (uma regra `ask`, um comando perigoso), a página mostra o mesmo diálogo de permissão que a IDE recebe por ACP: **permitir uma vez**, **permitir sempre**, **negar**, **negar sempre**. Sem resposta dentro do timeout (`CHATCLI_MCP_PERMISSION_TIMEOUT`, padrão 10 minutos) a ação é negada uma vez, então um navegador abandonado nunca deixa um loop pendurado.
Um turno de cada vez, como no terminal: enquanto um turno roda, enviar outro é recusado com um aviso claro em vez de enfileirar em silêncio. Fechar a aba cancela a execução.
### Provider e modelo
Os seletores mostram o que o motor alcança: providers com credenciais e, por provider, os modelos que o catálogo conhece mais o que a API do provider lista ao vivo. Escolher um define a rota dos turnos seguintes, sem mexer na seleção do terminal. Skills que fixam um modelo continuam vencendo nos turnos em que disparam.
### Mídia
| Recurso | Precisa de | O que faz |
| ----------------- | ----------------------------------------------- | ------------------------------------------------------------------------ |
| Entrada de imagem | um modelo com visão, ou o fallback de descrição | Anexe ou cole imagens; chegam ao turno como o `@file` |
| Entrada de voz | um backend de STT (`CHATCLI_STT_*`) | Grave no navegador, transcreva na sua máquina, o texto cai no compositor |
| Ler em voz alta | um backend de TTS (`CHATCLI_TTS_*`) | Um botão de ouvir em cada resposta |
| Geração de imagem | um provider de imagem (`CHATCLI_IMAGE_*`) | O botão de imagem transforma o texto do compositor numa imagem |
Recursos não configurados ficam escondidos, não quebrados.
## A API por trás da página
A página fala com uma pequena API JSON na mesma origem. Está documentada aqui porque um script pode acioná-la tão bem quanto a página, com o token do endereço:
| Endpoint | Propósito |
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/boot` | Tudo o que a página precisa ao carregar: idioma, tema, recursos, providers, tools, skills, comandos, recursos de memória, sessões, status e o histórico ao vivo |
| `POST /api/turn` | Executa um turno; a resposta é um stream de server-sent events (`run`, `chunk`, `thought`, `message`, `tool_start`, `tool_end`, `plan`, `permission`, `done`, `error`) |
| `POST /api/runs/{id}/permission` | Responde a um diálogo de permissão: `allow_once`, `allow_always`, `deny_once`, `deny_always` |
| `POST /api/runs/{id}/cancel` | Cancela o turno em execução |
| `GET /api/sessions`, `GET /api/sessions/{name}/messages`, `POST /api/session` | O catálogo de sessões, as mensagens de uma sessão salva e as ações de vincular/salvar/bifurcar/limpar |
| `GET /api/tools`, `POST /api/tools/{name}` | O catálogo de tools e uma chamada direta |
| `GET /api/skills`, `GET /api/skills/{name}`, `GET /api/commands`, `POST /api/command` | Skills, o conteúdo delas, os slash commands que a superfície pode executar, e executar um |
| `GET /api/resources`, `GET /api/resource?uri=` | Recursos de memória e contexto (`chatcli://memory/...`) |
| `GET /api/status`, `POST /api/defaults` | Rota, custo, orçamento e status MCP; troca do provider e modelo padrão |
| `POST /api/tts`, `POST /api/stt`, `POST /api/image` | Mídia, quando configurada |
Toda chamada carrega `X-Web-Token: `; o token nunca é aceito pela query, o Host precisa bater exatamente com o endereço vinculado (guarda contra DNS rebinding), e a página traz uma Content-Security-Policy estrita que não permite recurso externo algum.
## Privacidade e segurança
* Só loopback. Um pedido para escutar em outra interface é recusado.
* Um token por execução, 128 bits, em memória. Pare o processo e o endereço morre.
* A web UI roda o motor **desassistido** como MCP e ACP: comandos perigosos seguem `CHATCLI_MCP_DANGER` (`block` os transforma em recusas em linha) e o diálogo de permissão cobre as regras `ask`. `/policy` no terminal muda as regras para os dois.
* A página é um único arquivo embutido. Sem CDN, sem fontes, sem analytics, funciona offline.
## Configuração
| Configuração | Padrão | Significado |
| -------------------------------- | ------------- | ------------------------------------------------------------------ |
| `chatcli web --addr` | `127.0.0.1:0` | Endereço de escuta; só endereços de loopback |
| `chatcli web --session` | nenhum | Sessão salva para vincular no início |
| `chatcli web --no-browser` | desligado | Imprime o endereço em vez de abrir o navegador |
| `CHATCLI_MCP_PERMISSION_TIMEOUT` | `600s` | Quanto tempo um diálogo de permissão espera antes de negar uma vez |
| `CHATCLI_MCP_DANGER` | ask | `block` recusa comandos perigosos em linha |
| `CHATCLI_MCP_HUB` | ligado | `off` pula a retomada do Conversation Hub |
`/config web` mostra se a web UI está rodando, o endereço, o processo filho, a sessão vinculada e o arquivo de log (`~/.chatcli/web.log`).
## Relação com as outras superfícies
| Superfície | Fala com | Continuidade de sessão | Transmite | Permissões |
| ------------ | ----------------------------- | ---------------------- | --------------------- | ---------------------------- |
| Terminal | o motor diretamente | sua sessão vinculada | sim | prompts em linha |
| Web UI | backend RPC compartilhado | sessão vinculada + hub | SSE | diálogo no navegador |
| Servidor MCP | backend RPC compartilhado | sessão vinculada + hub | emit de linhas | elicitation |
| ACP | backend RPC compartilhado | sessão vinculada + hub | eventos estruturados | `session/request_permission` |
| Gateway | ChatCLI próprio, desassistido | hub | resposta por mensagem | automático |
O que cada processo está fazendo, como um grafo ao vivo. Abra do terminal da web UI com `/dash`: a web UI aparece como janela própria `web`, com seus turnos, chamadas de modelo, tools e skills.
Como uma sessão salva acompanha você pelo terminal, IDEs e canais.