Skip to content

Commit 2813b9e

Browse files
nikmd1306nikmd1306
committed
docs(readme): add documentation, license, and contributing guide
- add CONTRIBUTING.md with development and PR guidelines - add MIT LICENSE file - add comprehensive README and project logo - update CLAUDE.md to simplify build instructions and add commit workflow note
1 parent eca077a commit 2813b9e

File tree

5 files changed

+192
-3
lines changed

5 files changed

+192
-3
lines changed

‎CLAUDE.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,13 @@
11
# CLAUDE.md
22

3-
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4-
53
## Project
64

75
CWAI (Commits with AI) — Go CLI tool that generates conventional commit messages from staged git changes using OpenAI-compatible APIs.
86

97
## Build & Run
108

119
```bash
12-
make build # Build binary with version from git describe
10+
make build # Build binary
1311
make install # Install to $GOPATH/bin
1412
make clean # Remove compiled binary
1513
go test ./... # Run all tests
@@ -55,6 +53,10 @@ Staged changes → git diff → token truncation → prompt construction → AI
5553

5654
INI file at `~/.cwai`. Key settings: `CWAI_API_KEY`, `CWAI_API_URL`, `CWAI_MODEL`, `CWAI_LANGUAGE`, `CWAI_MAX_TOKENS_INPUT`, `CWAI_MAX_TOKENS_OUTPUT`, `CWAI_TEMPERATURE`, `CWAI_REASONING_EFFORT`, `CWAI_VERBOSITY`, `CWAI_STRUCTURED_OUTPUT`.
5755

56+
## Commits
57+
58+
When asked to commit, use `cwai` instead of `git commit`: stage files with `git add`, then run `cwai` to generate and apply the commit message. Use `cwai --yes` (or `cwai -y`) for non-interactive mode (CI, scripts, agents).
59+
5860
## Conventions
5961

6062
- Conventional Commits format: `type(scope): description` + optional bullet points

‎CONTRIBUTING.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Contributing to cwai
2+
3+
Thanks for your interest in contributing! This document covers everything you need to get started.
4+
5+
## Development Setup
6+
7+
### Prerequisites
8+
9+
- Go 1.23.4+
10+
- Git
11+
12+
### Build & test
13+
14+
```bash
15+
git clone https://github.com/nikmd1306/cwai.git
16+
cd cwai
17+
18+
make build # Build binary
19+
make install # Install to $GOPATH/bin
20+
make clean # Remove compiled binary
21+
go test ./... # Run all tests
22+
```
23+
24+
## How to Contribute
25+
26+
### Reporting bugs
27+
28+
Open an [issue](https://github.com/nikmd1306/cwai/issues/new?template=bug_report.md) with:
29+
- Steps to reproduce
30+
- Expected vs actual behavior
31+
- Go version, OS, cwai version
32+
33+
### Suggesting features
34+
35+
Open a [feature request](https://github.com/nikmd1306/cwai/issues/new?template=feature_request.md) describing the use case and proposed solution.
36+
37+
### Submitting code
38+
39+
1. Fork the repository
40+
2. Create a feature branch: `git checkout -b feat/my-feature`
41+
3. Make your changes
42+
4. Run tests: `go test ./...`
43+
5. Commit your changes — and yes, we expect [Conventional Commits](https://www.conventionalcommits.org/). You know a tool that can help with that, right? `cwai` ;)
44+
6. Push and open a Pull Request
45+
46+
## Pull Request Guidelines
47+
48+
- Conventional Commits for all commit messages (pro tip: `make install && cwai` — dogfood at its finest)
49+
- Add tests for new functionality
50+
- Ensure all existing tests pass
51+
- Keep PRs focused — one feature or fix per PR
52+
53+
## Code Style
54+
55+
- Format code with `gofmt`
56+
- Run `go vet ./...` before committing
57+
- Follow standard Go conventions and project structure

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 nikmd1306
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
<p align="center">
2+
<img src="assets/logo.png" width="128" alt="cwai logo">
3+
</p>
4+
5+
<h1 align="center">cwai</h1>
6+
7+
<p align="center">
8+
AI-powered conventional commit message generator from staged git changes.
9+
</p>
10+
11+
<p align="center">
12+
<a href="https://github.com/nikmd1306/cwai/actions/workflows/tests.yml"><img src="https://github.com/nikmd1306/cwai/actions/workflows/tests.yml/badge.svg" alt="CI"></a>
13+
<a href="https://github.com/nikmd1306/cwai/releases/latest"><img src="https://img.shields.io/github/v/release/nikmd1306/cwai" alt="Release"></a>
14+
<a href="https://pkg.go.dev/github.com/nikmd1306/cwai"><img src="https://pkg.go.dev/badge/github.com/nikmd1306/cwai.svg" alt="Go Reference"></a>
15+
<a href="https://goreportcard.com/report/github.com/nikmd1306/cwai"><img src="https://goreportcard.com/badge/github.com/nikmd1306/cwai" alt="Go Report Card"></a>
16+
<a href="LICENSE"><img src="https://img.shields.io/github/license/nikmd1306/cwai" alt="License"></a>
17+
</p>
18+
19+
---
20+
21+
## Features
22+
23+
- Generates [Conventional Commits](https://www.conventionalcommits.org/) messages from `git diff`
24+
- Works with any OpenAI-compatible API (OpenAI, Anthropic, local models)
25+
- Two modes: interactive standalone or silent `prepare-commit-msg` hook
26+
- Structured output support for consistent formatting
27+
- Smart diff truncation to fit model token limits
28+
29+
## Installation
30+
31+
### go install
32+
33+
```bash
34+
go install github.com/nikmd1306/cwai@latest
35+
```
36+
37+
### Binary releases
38+
39+
Download pre-built binaries from [Releases](https://github.com/nikmd1306/cwai/releases).
40+
41+
### From source
42+
43+
```bash
44+
git clone https://github.com/nikmd1306/cwai.git
45+
cd cwai
46+
make install
47+
```
48+
49+
## Quick Start
50+
51+
```bash
52+
# Initial setup (API key, model, language)
53+
cwai setup
54+
55+
# Stage changes and generate commit
56+
git add .
57+
cwai
58+
59+
# Or install as git hook for automatic messages
60+
cwai hook set
61+
```
62+
63+
### Standalone mode
64+
65+
```console
66+
$ cwai
67+
Staged files (3):
68+
internal/ai/client.go
69+
internal/prompt/prompt.go
70+
cmd/root.go
71+
72+
Generated commit message:
73+
74+
feat(ai): add structured output support for commit generation
75+
76+
[y]es / [e]dit / [r]egenerate / [n]o:
77+
```
78+
79+
### Hook mode
80+
81+
```bash
82+
cwai hook set # Install prepare-commit-msg hook
83+
cwai hook unset # Remove hook
84+
```
85+
86+
## Configuration
87+
88+
Config file: `~/.cwai` (INI format). Use `cwai config set KEY VALUE` or `cwai setup`.
89+
90+
| Key | Description | Default |
91+
|-----|-------------|---------|
92+
| `CWAI_API_KEY` | API key (required) | *not set* |
93+
| `CWAI_API_URL` | API base URL | `https://api.openai.com/v1` |
94+
| `CWAI_MODEL` | Model name | `gpt-4o-mini` |
95+
| `CWAI_LANGUAGE` | Commit message language | `en` |
96+
| `CWAI_MAX_TOKENS_INPUT` | Max input tokens for diff | `4096` |
97+
| `CWAI_MAX_TOKENS_OUTPUT` | Max output tokens | `500` |
98+
| `CWAI_TEMPERATURE` | Sampling temperature | *not set* |
99+
| `CWAI_REASONING_EFFORT` | Reasoning effort (for reasoning models) | *not set* |
100+
| `CWAI_VERBOSITY` | Output verbosity | *not set* |
101+
| `CWAI_STRUCTURED_OUTPUT` | Enable structured output (`true`/`false`) | *not set* |
102+
103+
## Contributing
104+
105+
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
106+
107+
## License
108+
109+
[MIT](LICENSE)

‎assets/logo.png‎

38.6 KB
Loading

0 commit comments

Comments
 (0)