Skip to main content
Contributions are welcome! ChatCLI is an open-source project licensed under the MIT License.

​
How to contribute

​
1. Fork and clone

# Fork the repository on GitHub and clone
git clone https://github.com/YOUR-USERNAME/chatcli.git
cd chatcli

​
2. Environment setup

# Prerequisites
go version  # Go 1.25+

# Install dependencies
go mod tidy

# Build
go build -o chatcli

# Run tests
go test ./...

​
3. Create a branch

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

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.

​
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 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: 
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.

​
Reporting bugs

Open an issue on GitHub with:
  • ChatCLI version (chatcli --version)
  • Operating system and Go version
  • Steps to reproduce
  • Expected vs observed behavior
  • Relevant logs (use LOG_LEVEL=debug)