# commits-to-issues

[![CI](https://github.com/amirhosseinkz/commits-to-issues/actions/workflows/ci.yml/badge.svg)](https://github.com/amirhosseinkz/commits-to-issues/actions/workflows/ci.yml)

**Generate GitHub issues from your git history.** Your commits already record what you
shipped; this turns them into closed GitHub issues, grouped into real units of work,
each with a checklist of what changed and a comment linking every commit.

A CLI and an MCP server for Claude Code, Codex, and Cursor. You see the whole plan
first; nothing is written until you say yes. Run it again and it skips what already exists.

Use it when the issue tracker fell behind the code: a solo project that never had
issues, a sprint nobody logged, or a repo you are about to open-source and want a
readable history for.

## Quick start

Requires Python 3.10+ and a GitHub token (`gh auth login` is enough).

```bash
uvx commits-to-issues --since 2026-09-01
```

```text
42 commits in ~/code/shop → 7 issues for octo/shop

 id  worked                   area            kind         commits  title
  1  2026-09-01→2026-09-03    orders          enhancement        6  Add order export
  2  2026-09-04               auth            bug                2  Refresh expired sessions
  3  2026-09-08→2026-09-10    billing         enhancement        9  Support annual plans
...
Nothing was written to GitHub. Re-run with --apply to create and close these issues.
```

Then create them:

```bash
uvx commits-to-issues --since 2026-09-01 --apply
```

Each issue gets the `from-commits` label, plus `bug` or `enhancement` from conventional
commit types, and is closed as completed with a comment listing its commits.

## How commits are grouped

1. A path map you give it: `--module apps/web/=Web --module api/=API`
2. Otherwise the conventional-commit scope: `fix(auth): ...` → `auth`
3. Otherwise the top-level folder the commit touched most

A group splits when work pauses for more than three days (`--max-gap-days`). The
title comes from the largest commit in the group. Weekend work is dated on the next
business day.

Other options: `--until`, `--author`, `--github OWNER/REPO` (defaults to the `origin`
remote), `--skip 2,5`, and `--include-uncommitted`, which adds one open issue for work in progress.

## With an AI agent (MCP)

The same flow is an MCP server for Claude Code, Codex, Cursor, and other clients:

```bash
claude mcp add commits-to-issues -- uvx commits-to-issues mcp
```

- `plan_issues_from_commits` is read-only. It returns the proposed issues and a `plan_id`.
- `create_issues_from_commits` takes the `plan_id`, optional new `titles` and `skip` ids, and
  defaults to `dry_run=true`.

Try this prompt:

```text
Read this repository's git history since September 1 and propose GitHub issues
with plan_issues_from_commits. Show me the plan as a table. Don't create anything until I approve.
```

## Safe to retry

Every issue carries a hidden marker derived from its first commit. Before writing,
`commits-to-issues` lists the repo's `from-commits` issues and skips any it already made,
so a re-run, or a retry after a network error, never duplicates an issue. Writes are
spaced out and back off on GitHub rate limits.

## Limits

- GitHub does not let you backdate an issue, so the real dates appear in the issue body
  ("Worked: 2026-09-08 → 2026-09-10"), not as its created date.
- Commit messages are the only evidence. No tests are run.

## Also by the author

[plane-workflow-mcp](https://github.com/amirhosseinkz/plane-workflow-mcp) does the same
for [Plane](https://plane.so/), cloud or self-hosted, plus a planning workflow for agents.

MIT licensed.