@sugarmo/aicommits 1.15.0 → 1.16.1

package/README.md

@@ -63,8 +63,6 @@ For example, you can stage all changes in tracked files with as you commit:
 aicommits --all # or -a
 ```
 
-> 👉 **Tip:** Use the `aic` alias if `aicommits` is too long for you.
-
 #### Generate multiple recommendations
 
 Sometimes the recommended commit message isn't the best so you want it to generate a few to pick from. You can generate multiple commit messages at once by passing in the `--generate <i>` flag, where 'i' is the number of generated messages:
@@ -82,49 +80,33 @@ If your environment does not provide an interactive TTY, skip prompts explicitly
 aicommits --confirm # or -y / --yes
 ```
 
-#### Generate title + optional details
-
-Enable `details` when you want a body only when the title is not clear enough on its own:
+#### Guide output with Markdown
 
-```sh
-aicommits --details
-```
+Commit message style is now controlled by a Markdown file instead of individual formatting flags.
 
-If you prefer a bullet-list body style:
+By default, aicommits reads `~/.aicommits/message.md`. The file is created automatically on first use.
 
 ```sh
-aicommits --details --details-style list
+aicommits
 ```
 
-If you prefer markdown-formatted detail body:
+To use a different Markdown file for one run:
 
 ```sh
-aicommits --details --details-style markdown
+aicommits --message-file release-message.md
 ```
 
-#### Default style
-
-The generator uses a GitHub Copilot-like style by default and prefers commit titles with a concrete file/class/module anchor so commit lists are easier to scan.
-
-You can still fine-tune output using custom instructions:
-
-```sh
-aicommits --details --instructions "Use shorter body sentences and prioritize class names in the title"
-```
+The default file includes editable instructions for language, title format, body rules, and style. If you were previously using settings like `type`, `details`, `instructions`, or `conventional-*`, upgrade once and those values will be migrated into `message.md` automatically.
 
-#### Customize conventional format
+#### Post-process the AI response
 
-You can combine conventional commits with custom output format and type mapping:
+You can run an executable after the model responds and before the message is shown or committed.
 
 ```sh
-aicommits --type conventional --conventional-format "<type>(<scope>): <subject>" --conventional-types '{"feature":"Introduce a feature","bugfix":"Fix defects"}'
+aicommits --post-response-script rewrite-message.sh
 ```
 
-By default, conventional mode omits scope and uses `type: subject`. You can enable scope preference (for example `refactor(RecentScrollshotController): ...`) when there is a clear dominant file/class/module:
-
-```sh
-aicommits --conventional-scope true
-```
+The script receives the raw AI message on stdin and must write the final message to stdout.
 
 ### Git hook
 
@@ -199,7 +181,7 @@ aicommits config set api-key=<your-api-key>
 You can also set multiple configuration options at once by separating them with spaces, like
 
 ```sh
-aicommits config set api-key=<your-api-key> generate=3 locale=en
+aicommits config set api-key=<your-api-key> generate=3
 ```
 
 ### Options
@@ -207,13 +189,21 @@ aicommits config set api-key=<your-api-key> generate=3 locale=en
 
 Required
 
-API key for your chat completions provider.
+API key for your configured API provider.
+
+You can also keep the secret outside `config.toml` and reference an environment variable instead:
+
+```toml
+api-key = "env:OPENAI_API_KEY"
+```
+
+`${OPENAI_API_KEY}` is also supported if you prefer shell-style syntax.
 
 #### base-url
 
 Required
 
-Base URL used for chat completions requests.
+Base URL used for API requests.
 
 ```sh
 aicommits config set base-url=https://api.openai.com/v1
@@ -242,13 +232,6 @@ model = "gpt-5.2-codex"
 base-url = "https://api.example.com/v1"
 ```
 
-#### locale
-Default: `en`
-
-The locale to use for the generated commit messages. Consult the list of codes in: https://wikipedia.org/wiki/List_of_ISO_639-1_codes.
-
-Common aliases are normalized automatically (for example `cn` -> `zh-CN`).
-
 #### generate
 
 Default: `1`
@@ -271,7 +254,20 @@ aicommits config set proxy=
 
 Default: `gpt-3.5-turbo`
 
-The Chat Completions (`/v1/chat/completions`) model to use.
+The model to use for generation.
+
+#### api-mode
+
+Default: `responses`
+
+Controls which API primitive aicommits uses.
+
+- `responses`: default and recommended for new setups
+- `chat`: legacy compatibility mode
+
+```sh
+aicommits config set api-mode=chat
+```
 
 
 #### timeout
@@ -308,59 +304,24 @@ Use `0` to switch back to auto mode:
 aicommits config set context-window=0
 ```
 
-#### title-length-guide
-Guidance target for commit title length.
-
-Default: `50`
-
-```sh
-aicommits config set title-length-guide=100
-```
+#### message-path
 
-`max-length` is kept as a compatibility alias.
+Default: `message.md`
 
-#### type
-
-Default: plain format
-
-Set commit type formatting:
-
-```sh
-aicommits config set type=conventional
-```
-
-#### details
-
-Default: `false`
-
-Set this to `true` to allow optional body details. If the title already explains the change clearly, it can still return title only:
-
-```sh
-aicommits config set details=true
-```
-
-#### details-style
-
-Default: `paragraph`
-
-Controls body formatting when `details=true`.
-
-Allowed values: `paragraph`, `list`, `markdown`
+Relative paths resolve from `~/.aicommits/`. The referenced Markdown file controls how commit messages should be written.
 
 ```sh
-aicommits config set details-style=list
-aicommits config set details-style=markdown
+aicommits config set message-path=release-message.md
 ```
 
-#### detail-column-guide
+#### post-response-script
 
-Default: `72`
+Default: empty
 
-Guidance target for where detail/body lines should wrap.
-Applies to `paragraph` and `list` styles. `markdown` style keeps original line breaks.
+Relative paths resolve from `~/.aicommits/`. The executable receives the AI response on stdin and must write the final commit message to stdout.
 
 ```sh
-aicommits config set detail-column-guide=88
+aicommits config set post-response-script=rewrite-message.sh
 ```
 
 #### show-reasoning
@@ -368,7 +329,7 @@ aicommits config set detail-column-guide=88
 Default: `false`
 
 By default, aicommits shows normal analyzing progress.  
-If the model emits reasoning tokens, it switches to elapsed thinking time (for example `Thinking for 1m 12s`).
+If the API emits reasoning content, it switches to elapsed thinking time (for example `The AI (gpt-5.4) is thinking for 1m 12s`).
 Enable this option to print full streamed model reasoning (debug mode):
 
 ```sh
@@ -381,55 +342,36 @@ Or enable for a single run:
 aicommits --show-reasoning
 ```
 
-#### instructions
-
-Default: empty
-
-Additional custom prompt instructions:
+#### reasoning-effort
 
-```sh
-aicommits config set instructions="Use short and direct wording"
-```
+Default: unset
 
-#### conventional-format
+Controls the model reasoning effort requested by aicommits.
 
-Default: `<type>[optional (<scope>)]: <commit message>`
+- `none`, `low`, `medium`, `high`, `xhigh`: request an explicit reasoning level
 
-Customize the conventional output template:
+This is the supported way to configure reasoning effort.  
+aicommits maps it to `reasoning.effort` for Responses API requests and `reasoning_effort` for Chat requests.
 
 ```sh
-aicommits config set conventional-format="<type>(<scope>): <subject>"
+aicommits config set reasoning-effort=low
 ```
 
-#### conventional-types
-
-Default: built-in conventional type map
-
-Customize type descriptions with JSON:
-
-```sh
-aicommits config set conventional-types='{"feature":"Introduce a feature","bugfix":"Fix defects"}'
-```
-
-#### conventional-scope
-
-Default: `false`
-
-When enabled, conventional commits strongly prefer `type(scope): subject` using the primary file/class/module as scope.  
-When disabled (default), conventional commits prefer `type: subject`.
+Or for a single run:
 
 ```sh
-aicommits config set conventional-scope=true
+aicommits --reasoning-effort high
 ```
 
 #### request-options
 
 Default: empty
 
-Raw JSON object merged into the Chat Completions request body.
+Raw JSON object merged into the selected API request body.
 
-Use this for provider-specific fields (for example, disabling reasoning/thinking when supported).  
-Internal fields `model`, `messages`, and `stream` are controlled by aicommits and cannot be overridden.
+Use this for provider-specific fields that do not already have a dedicated aicommits option.  
+For reasoning effort, prefer `reasoning-effort` instead of passing `reasoning` or `reasoning_effort` manually.  
+Internal fields `model`, `messages`, `instructions`, `input`, and `stream` are controlled by aicommits and cannot be overridden.
 
 ```sh
 aicommits config set request-options='{"thinking":{"type":"disabled"}}'
@@ -437,7 +379,7 @@ aicommits config set request-options='{"thinking":{"type":"disabled"}}'
 
 ## How it works
 
-This CLI tool runs `git diff` to grab your latest code changes, sends them to your configured chat completions API, then returns the generated commit message.
+This CLI tool runs `git diff` to grab your latest code changes, sends them to your configured API provider using the Responses API by default, then returns the generated commit message. You can switch back to Chat Completions with `api-mode=chat`.
 
 Video coming soon where I rebuild it from scratch to show you how to easily build your own CLI tools powered by AI.