# kittylog
[](https://github.com/cellwebb/kittylog/actions/workflows/ci.yml)
[](https://badge.fury.io/py/kittylog)
[](https://www.python.org/downloads/)
[](https://codecov.io/gh/cellwebb/kittylog)
[](https://github.com/psf/black)
[](LICENSE)
**LLM-powered changelog generation from git tags and commits.** Automatically analyzes your repository history to create well-structured changelog entries following the [Keep a Changelog](https://keepachangelog.com/) format.
## Key Features
- **LLM-powered analysis** of commits, file changes, and code patterns to categorize changes
- **Multi-provider support** for Anthropic, Cerebras, Chutes, Custom Anthropic/OpenAI endpoints, DeepSeek, Fireworks, Gemini, Groq, LM Studio, MiniMax, Mistral, Ollama, OpenAI, OpenRouter, StreamLake, Synthetic, Together AI, Z.AI (including coding plans)
- **Smart tag detection** - automatically detects which tags need changelog entries
- **Keep a Changelog format** with proper Added/Changed/Fixed categorization
- **Unreleased section** tracking for commits since last tag
- **Interactive workflow** - review and approve content before saving
- **Intelligent version detection** - avoids duplicates by comparing with existing changelog
## Grouping Modes
kittylog supports three different grouping strategies to accommodate various project workflows:
### 🏷️ **Tags Mode** (default)
Uses git tags as changelog boundaries. Perfect for projects with consistent release tagging.
```bash
kittylog --grouping-mode tags # Default behavior
```
### 📅 **Date Mode**
Groups commits by date (daily/weekly/monthly). Ideal for projects without regular tags.
```bash
kittylog --grouping-mode dates --date-grouping daily # Group by day
kittylog --grouping-mode dates --date-grouping weekly # Group by week
kittylog --grouping-mode dates --date-grouping monthly # Group by month
```
### ⏱️ **Gap Mode**
Groups commits by activity sessions with configurable time gaps. Great for irregular development patterns.
```bash
kittylog --grouping-mode gaps --gap-threshold 4.0 # 4-hour gaps (default)
kittylog --grouping-mode gaps --gap-threshold 24 # 24-hour gaps
```
**When to use each mode:**
- **Tags**: Formal release process with semantic versioning
- **Dates**: Regular development without formal releases
- **Gaps**: Irregular development with distinct work sessions
## Installation
**Try without installing:**
```sh
uvx kittylog init # Set up configuration
uvx kittylog # Generate changelog
```
**Install permanently:**
```sh
pipx install kittylog
kittylog init # Interactive setup
```
## Usage
```sh
# Basic usage (from git repository root)
kittylog
# Common options
kittylog --dry-run # Preview only
kittylog -y # Auto-accept
kittylog -h "Breaking changes" # Add context hint
```
**How it works:**
1. Detects changelog boundaries using your chosen grouping mode (tags/dates/gaps)
2. Analyzes commits and file changes between boundaries
3. Generates categorized changelog entries with AI that understands the grouping context
4. Shows preview and prompts for confirmation
5. Updates your CHANGELOG.md file with properly formatted sections
See [USAGE.md](USAGE.md) for detailed documentation.
## Requirements
- Python 3.10+
- Git repository (tags optional - can use date/gap grouping)
- AI provider API key
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. This project uses kittylog to maintain its own changelog!
## License
MIT License - see [LICENSE](LICENSE) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "kittylog",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "automation, changelog, git, github, pull-request, tags, versioning",
"author": null,
"author_email": "cellwebb <cellwebb@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/aa/6c/894e966e7346513ec27c03f1854b67608a58755f8149b509061dcb4af4de/kittylog-1.4.0.tar.gz",
"platform": null,
"description": "# kittylog\n\n[](https://github.com/cellwebb/kittylog/actions/workflows/ci.yml)\n[](https://badge.fury.io/py/kittylog)\n[](https://www.python.org/downloads/)\n[](https://codecov.io/gh/cellwebb/kittylog)\n[](https://github.com/psf/black)\n[](LICENSE)\n\n**LLM-powered changelog generation from git tags and commits.** Automatically analyzes your repository history to create well-structured changelog entries following the [Keep a Changelog](https://keepachangelog.com/) format.\n\n## Key Features\n\n- **LLM-powered analysis** of commits, file changes, and code patterns to categorize changes\n- **Multi-provider support** for Anthropic, Cerebras, Chutes, Custom Anthropic/OpenAI endpoints, DeepSeek, Fireworks, Gemini, Groq, LM Studio, MiniMax, Mistral, Ollama, OpenAI, OpenRouter, StreamLake, Synthetic, Together AI, Z.AI (including coding plans)\n- **Smart tag detection** - automatically detects which tags need changelog entries\n- **Keep a Changelog format** with proper Added/Changed/Fixed categorization\n- **Unreleased section** tracking for commits since last tag\n- **Interactive workflow** - review and approve content before saving\n- **Intelligent version detection** - avoids duplicates by comparing with existing changelog\n\n## Grouping Modes\n\nkittylog supports three different grouping strategies to accommodate various project workflows:\n\n### \ud83c\udff7\ufe0f **Tags Mode** (default)\n\nUses git tags as changelog boundaries. Perfect for projects with consistent release tagging.\n\n```bash\nkittylog --grouping-mode tags # Default behavior\n```\n\n### \ud83d\udcc5 **Date Mode**\n\nGroups commits by date (daily/weekly/monthly). Ideal for projects without regular tags.\n\n```bash\nkittylog --grouping-mode dates --date-grouping daily # Group by day\nkittylog --grouping-mode dates --date-grouping weekly # Group by week\nkittylog --grouping-mode dates --date-grouping monthly # Group by month\n```\n\n### \u23f1\ufe0f **Gap Mode**\n\nGroups commits by activity sessions with configurable time gaps. Great for irregular development patterns.\n\n```bash\nkittylog --grouping-mode gaps --gap-threshold 4.0 # 4-hour gaps (default)\nkittylog --grouping-mode gaps --gap-threshold 24 # 24-hour gaps\n```\n\n**When to use each mode:**\n\n- **Tags**: Formal release process with semantic versioning\n- **Dates**: Regular development without formal releases\n- **Gaps**: Irregular development with distinct work sessions\n\n## Installation\n\n**Try without installing:**\n\n```sh\nuvx kittylog init # Set up configuration\nuvx kittylog # Generate changelog\n```\n\n**Install permanently:**\n\n```sh\npipx install kittylog\nkittylog init # Interactive setup\n```\n\n## Usage\n\n```sh\n# Basic usage (from git repository root)\nkittylog\n\n# Common options\nkittylog --dry-run # Preview only\nkittylog -y # Auto-accept\nkittylog -h \"Breaking changes\" # Add context hint\n```\n\n\n\n**How it works:**\n\n1. Detects changelog boundaries using your chosen grouping mode (tags/dates/gaps)\n2. Analyzes commits and file changes between boundaries\n3. Generates categorized changelog entries with AI that understands the grouping context\n4. Shows preview and prompts for confirmation\n5. Updates your CHANGELOG.md file with properly formatted sections\n\nSee [USAGE.md](USAGE.md) for detailed documentation.\n\n## Requirements\n\n- Python 3.10+\n- Git repository (tags optional - can use date/gap grouping)\n- AI provider API key\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. This project uses kittylog to maintain its own changelog!\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "AI-powered changelog updater that uses git tags to update CHANGELOG.md files",
"version": "1.4.0",
"project_urls": {
"Changelog": "https://github.com/cellwebb/kittylog/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/cellwebb/kittylog#readme",
"Homepage": "https://github.com/cellwebb/kittylog",
"Issues": "https://github.com/cellwebb/kittylog/issues",
"Repository": "https://github.com/cellwebb/kittylog.git",
"Source": "https://github.com/cellwebb/kittylog"
},
"split_keywords": [
"automation",
" changelog",
" git",
" github",
" pull-request",
" tags",
" versioning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "be74ae8bc47864e6b38f36ab63630f356fa496cd2a11f39a019a59f197bab19b",
"md5": "60b4953ba60e662934c63276a74e2b22",
"sha256": "e7d3f37834d92cf3fae99fdf04195b60e8ed117663b32ef3b113bb19afb53247"
},
"downloads": -1,
"filename": "kittylog-1.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "60b4953ba60e662934c63276a74e2b22",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 77847,
"upload_time": "2025-11-01T04:38:05",
"upload_time_iso_8601": "2025-11-01T04:38:05.001632Z",
"url": "https://files.pythonhosted.org/packages/be/74/ae8bc47864e6b38f36ab63630f356fa496cd2a11f39a019a59f197bab19b/kittylog-1.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "aa6c894e966e7346513ec27c03f1854b67608a58755f8149b509061dcb4af4de",
"md5": "0a700ea9a39d7846e7a26f48e5f0c9f6",
"sha256": "d19134e1a34bc277ccddc0153ceb4c792b3a747297fecda47653a782a7af27e7"
},
"downloads": -1,
"filename": "kittylog-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "0a700ea9a39d7846e7a26f48e5f0c9f6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 57734,
"upload_time": "2025-11-01T04:38:06",
"upload_time_iso_8601": "2025-11-01T04:38:06.030673Z",
"url": "https://files.pythonhosted.org/packages/aa/6c/894e966e7346513ec27c03f1854b67608a58755f8149b509061dcb4af4de/kittylog-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-01 04:38:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cellwebb",
"github_project": "kittylog",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "kittylog"
}
JSON
