Detalhes do Projeto Claude Code UI

Visão Geral do Projeto

Claude Code UI é uma interface de usuário de código aberto, amigável para web e dispositivos móveis, projetada especificamente para o Claude Code CLI oficial da Anthropic. Este projeto permite aos usuários visualizar e gerenciar todas as sessões e projetos do Claude Code localmente ou remotamente, da mesma forma que fariam com o CLI. Isso oferece aos usuários uma interface completa que funciona em qualquer lugar.

Recursos do Projeto

🎨 Design Responsivo

• Compatibilidade Multiplataforma: Suporte contínuo para desktops, tablets e dispositivos móveis
• Layout Adaptável: Barra lateral recolhível e priorização inteligente de conteúdo
• Amigável ao Toque: Gestos de deslizar e navegação por toque
• Navegação Móvel: Barra de abas inferior para fácil acesso com o polegar

💬 Interface de Chat Interativa

• Chat Integrado: Interface de chat integrada para comunicação contínua com o Claude Code
• Comunicação em Tempo Real: Transmissão de respostas do Claude via conexão WebSocket
• Gerenciamento de Sessões: Retome conversas anteriores ou inicie novas sessões
• Histórico de Mensagens: Histórico completo de conversas com carimbos de data/hora e metadados
• Suporte a Múltiplos Formatos: Texto, blocos de código e referências de arquivos

🖥️ Funcionalidade de Terminal Integrada

• Acesso Direto ao CLI: Acesse diretamente o Claude Code CLI através da funcionalidade de shell integrada
• Gerenciamento de Processos: Geração e gerenciamento de processos integrados ao Claude CLI
• Execução de Comandos: Suporte para todos os comandos do Claude Code CLI

📁 Explorador de Arquivos

• Árvore de Arquivos Interativa: Árvore de arquivos interativa com destaque de sintaxe e edição em tempo real
• Edição de Arquivos em Tempo Real: Leia, modifique e salve arquivos diretamente na interface
• Destaque de Sintaxe: Suporte para várias linguagens de programação
• Operações de Arquivos: Crie, renomeie, exclua arquivos e diretórios

💾 Persistência de Sessões

• Salvamento Automático: Todas as conversas são salvas automaticamente
• Organização de Sessões: Sessões agrupadas por projeto e carimbo de data/hora
• Operações de Sessões: Renomeie, exclua e exporte o histórico de conversas
• Sincronização Entre Dispositivos: Acesse sessões de qualquer dispositivo

Arquitetura Técnica

Diagrama de Arquitetura do Sistema

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend │ │ Backend │ │ Claude CLI │
│ (React/Vite) │◄──►│ (Express/WS) │◄──►│ Integration │
└─────────────────┘ └─────────────────┘ └─────────────────┘

Pilha de Tecnologia do Backend

• Servidor Express: Fornece API RESTful e serviço de arquivos estáticos
• Servidor WebSocket: Usado para comunicação de chat e atualização de projetos
• Integração Claude CLI: Geração e gerenciamento de processos
• Gerenciamento de Sessões: Análise de JSONL e persistência de conversas
• API do Sistema de Arquivos: Fornece o explorador de arquivos para projetos

Pilha de Tecnologia do Frontend

• React 18: Arquitetura de componentes moderna, usando Hooks
• CodeMirror: Editor de código avançado, com destaque de sintaxe
• Vite: Ferramenta de construção rápida e servidor de desenvolvimento
• Tailwind CSS: Framework CSS utilitário-primeiro

Instalação e Configuração

Requisitos do Sistema

• Node.js v16 ou superior
• Claude Code CLI instalado e configurado

Passos de Instalação

1. Clonar o Repositório:

   git clone https://github.com/siteboon/claudecodeui.git
   cd claudecodeui
   

2. Instalar Dependências:

   npm install
   

3. Configurar Ambiente:

   cp .env.example .env
   # Edite o arquivo .env conforme necessário
   

4. Iniciar o Aplicativo:

   # Modo de desenvolvimento (com hot reload)
   npm run dev
   

5. Abrir o Navegador:

   • Ambiente de desenvolvimento: http://localhost:3001

Configurações de Segurança

🔒 Lembrete Importante de Segurança

Todas as ferramentas do Claude Code estão desativadas por padrão. Isso evita que operações potencialmente prejudiciais sejam executadas automaticamente.

Para usar a funcionalidade completa do Claude Code, você precisará ativar as ferramentas manualmente:

1. Abrir Configurações de Ferramentas: Clique no ícone de engrenagem na barra lateral
2. Ativação Seletiva: Ative apenas as ferramentas que você precisa
3. Aplicar Configurações: Suas preferências serão salvas localmente

Método Recomendado: Comece ativando as ferramentas básicas e adicione mais funcionalidades gradualmente, conforme necessário.

Principais Funcionalidades

Gerenciamento de Projetos

• Descoberta Automática de Projetos: A UI descobre automaticamente os projetos do Claude Code em ~/.claude/projects/
• Navegador Visual de Projetos: Exibe todos os projetos disponíveis com seus metadados e contagem de sessões
• Operações de Projeto: Renomeie, exclua e organize projetos
• Navegação Inteligente: Acesso rápido a projetos e sessões recentes

Gerenciamento de Arquivos

• Navegação da Estrutura do Projeto: Com funcionalidade de navegação expandir/recolher
• Edição em Tempo Real: Modifique arquivos diretamente na interface
• Operações de Arquivos: Funcionalidade completa de gerenciamento de arquivos e diretórios

Gerenciamento de Sessões

• Armazenamento Persistente: Todas as sessões são salvas automaticamente
• Histórico: Rastreamento completo do histórico de conversas
• Suporte a Múltiplas Sessões: Gerencie várias sessões de projeto simultaneamente

Solução de Problemas

Problema Comum 1: A UI não exibe projetos ou a lista de projetos está vazia

Solução:

• Certifique-se de que o Claude CLI esteja instalado corretamente
• Execute o comando claude em pelo menos um diretório de projeto para inicializá-lo
• Verifique se o diretório ~/.claude/projects/ existe e tem as permissões apropriadas

Problema Comum 2: Arquivos não carregam, erros de permissão, diretórios vazios

Solução:

• Verifique as permissões do diretório do projeto (use ls -la no terminal)
• Verifique se o caminho do projeto existe e está acessível
• Consulte os logs do console do servidor para obter informações detalhadas sobre erros
• Certifique-se de não tentar acessar diretórios do sistema fora do escopo do projeto