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

# Contributing to ChatCLI

> Guide to contributing to the ChatCLI project -- from local setup to submitting pull requests.

Contributions are welcome! ChatCLI is an open-source project licensed under the **MIT License**.

## How to contribute

### 1. Fork and clone

```bash theme={"system"}
# Fork the repository on GitHub and clone
git clone https://github.com/YOUR-USERNAME/chatcli.git
cd chatcli
```

### 2. Environment setup

```bash theme={"system"}
# Prerequisites
go version  # Go 1.25+

# Install dependencies
go mod tidy

# Build
go build -o chatcli

# Run tests
go test ./...
```

### 3. Create a branch

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

### 4. Make your changes

* Follow existing code patterns
* Add tests for new features
* Keep commits small and focused

### 5. Submit the Pull Request

```bash theme={"system"}
git add .
git commit -m "feat: clear description of the change"
git push origin feature/my-feature
```

Open a Pull Request on the [main repository](https://github.com/diillson/chatcli).

***

## Project structure

The codebase follows a modular architecture with SOLID decomposition. Major monolithic files have been split into focused modules:

* `cli/cli.go` (\~923 lines) + 7 extracted files (`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 lines) + 4 extracted files
* `cli/command_handler.go` (\~185 lines) + 4 extracted files
* `server/handler.go` (\~420 lines) + 3 extracted files
* `cli/context_handler.go` (\~385 lines) + 3 extracted files

See the [architecture documentation](/reference/architecture) to understand the complete organization of packages and components.

The project has **970 tests** with 0 failures, including the `cli/mcp`, `cli/ctxmgr`, and `llm/fallback` packages.

***

## Building with version information

For builds that inject version, commit, and date:

```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
```

***

## Adding a new LLM provider

1. Create a package in `llm/myprovider/`
2. Implement the `LLMClient` interface (and `ToolAwareClient` if it supports tool use)
3. Add auto-registration via `init()` in `llm/registry`
4. Define environment variables in `config/`
5. Add i18n translations in `i18n/`

The provider will be detected automatically -- no need to edit `switch/case` blocks.

***

## Creating a plugin

See the full guide at [Plugin System](/features/plugin-system).

***

## Reporting bugs

Open an [issue on GitHub](https://github.com/diillson/chatcli/issues) with:

* ChatCLI version (`chatcli --version`)
* Operating system and Go version
* Steps to reproduce
* Expected vs observed behavior
* Relevant logs (use `LOG_LEVEL=debug`)