> ## 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.

# Contribuindo com o ChatCLI

> Guia para contribuir com o projeto ChatCLI — desde o setup local até o envio de pull requests.

Contribuições são bem-vindas! O ChatCLI é um projeto open-source licenciado sob a **Licença MIT**.

## Como contribuir

### 1. Fork e clone

```bash theme={"system"}
# Fork o repositório no GitHub e clone
git clone https://github.com/SEU-USUARIO/chatcli.git
cd chatcli
```

### 2. Setup do ambiente

```bash theme={"system"}
# Pré-requisitos
go version  # Go 1.25+

# Instalar dependências
go mod tidy

# Compilar
go build -o chatcli

# Rodar testes
go test ./...
```

### 3. Crie uma branch

```bash theme={"system"}
git checkout -b feature/minha-feature
```

### 4. Faça suas alterações

* Siga os padrões de código existentes
* Adicione testes para novas funcionalidades
* Mantenha commits pequenos e focados

### 5. Envie o Pull Request

```bash theme={"system"}
git add .
git commit -m "feat: descrição clara da mudança"
git push origin feature/minha-feature
```

Abra um Pull Request no [repositório principal](https://github.com/diillson/chatcli).

***

## Estrutura do projeto

O código segue uma arquitetura modular com decomposição SOLID. Os principais arquivos monolíticos foram divididos em módulos focados:

* `cli/cli.go` (\~923 linhas) + 7 arquivos extraídos (`cli_helpers.go`, `cli_history.go`, `cli_mode.go`, `cli_output.go`, `cli_prompt.go`, `cli_session.go`, `cli_tools.go`)
* `cli/agent_mode.go` (\~1498 linhas) + 4 arquivos extraídos
* `cli/command_handler.go` (\~185 linhas) + 4 arquivos extraídos
* `server/handler.go` (\~420 linhas) + 3 arquivos extraídos
* `cli/context_handler.go` (\~385 linhas) + 3 arquivos extraídos

Veja a [documentação de arquitetura](/pt/reference/architecture) para entender a organização completa dos pacotes e componentes.

O projeto conta com **970 testes** com 0 falhas, incluindo os pacotes `cli/mcp`, `cli/ctxmgr` e `llm/fallback`.

***

## Compilação com informações de versão

Para builds que injetam versão, commit e data:

```bash theme={"system"}
VERSION=$(git describe --tags --always --dirty 2>/dev/null || echo "dev")
COMMIT_HASH=$(git rev-parse --short HEAD)
BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

go build -ldflags "\
  -X github.com/diillson/chatcli/version.Version=${VERSION} \
  -X github.com/diillson/chatcli/version.CommitHash=${COMMIT_HASH} \
  -X github.com/diillson/chatcli/version.BuildDate=${BUILD_DATE}" \
  -o chatcli main.go
```

***

## Adicionando um novo provedor LLM

1. Crie um pacote em `llm/meuprovedor/`
2. Implemente a interface `LLMClient` (e `ToolAwareClient` se suportar tool use)
3. Adicione auto-registro via `init()` no `llm/registry`
4. Defina as variáveis de ambiente no `config/`
5. Adicione traduções i18n em `i18n/`

O provedor será detectado automaticamente — sem precisar editar blocos `switch/case`.

***

## Criando um plugin

Veja o guia completo em [Sistema de Plugins](/pt/features/plugin-system).

***

## Reportando bugs

Abra uma [issue no GitHub](https://github.com/diillson/chatcli/issues) com:

* Versão do ChatCLI (`chatcli --version`)
* Sistema operacional e versão do Go
* Passos para reproduzir
* Comportamento esperado vs observado
* Logs relevantes (use `LOG_LEVEL=debug`)