# smart-commit-host-agent

`smart-commit-host-agent` is a shell-first tool for AI-assisted commit review, commit-message generation, optional Git execution, PR/MR creation, and local reporting.

It uses the same workflow surface as [`smart-commit-copilot-cli`](https://www.npmjs.com/package/smart-commit-copilot-cli), but it does **not** call an LLM HTTP API. When a command needs model text, it pauses for a Host Agent (Cursor, Codex, …) to write a turn response, then continues the same session.

Use it when you want one repeatable workflow that can run from:

- Cursor / Codex (or similar) agent skills
- your terminal
- shell scripts that orchestrate the Host-Agent loop

It can:

- inspect staged changes
- run AI review and gate on the result
- review existing GitHub pull requests or GitLab merge requests by URL
- list and batch-review your related open pull requests or merge requests
- generate or validate commit messages
- optionally create a commit
- optionally push the current branch
- auto-create GitHub PRs or GitLab MRs after a successful push when configured
- create or dry-run PR/MR content through standalone `pull-request create`
- review existing PR/MR URLs through standalone `pull-request review`
- list your related open PRs/MRs through `my-pull-request list`
- serially review your related open PRs/MRs through `my-pull-request batch-review`
- persist successful run history in pass history
- generate local or AI-enhanced daily, yesterday, weekly, last-week, monthly, last-month, quarterly, last-quarter, or yearly Markdown work reports

It does **not**:

- call OpenAI-, Anthropic-, or Cursor-Agent HTTP APIs itself
- accept `--api-key` / `--base-url` / `--model` / `--llm-provider`
- require `SMART_COMMIT_API_KEY`

## Who This Is For

This tool is a good fit if you want to:

- review staged changes before committing
- standardize commit messages
- run commit / review / PR workflows inside an agent that already has LLM capability
- avoid putting LLM API keys and `connection.*` into skill or automation config
- automate review-to-PR/MR flows from skills or scripts
- keep a lightweight pass history for successful runs
- generate periodic reports from local pass history

If you are using this for the first time, start with review-only mode and keep Git side effects disabled. Enable commit, push, and PR/MR creation gradually after you trust the workflow.

## What Happens In A Typical Run

At a high level, `smart-commit-host-agent bridge` does this:

1. resolves config and `env:VAR_NAME` references (no LLM connection)
2. verifies `--repo` and reads the staged diff, auto-staging only if configured
3. generates or validates the commit message, unless `--review-only` is used
4. when model text is required, pauses for a Host Agent turn (`status: "needs_host_agent"`), then resumes with `--session`
5. runs AI review and applies the score threshold
6. optionally creates a local commit, pushes, and creates a PR/MR
7. optionally records the furthest successful stage into pass history

| Step | When it runs | What it does | Output / side effect |
| --- | --- | --- | --- |
| Resolve config | Every `bridge` run | Merges CLI flags, environment variables, config file values, and defaults; resolves `env:...` references; rejects LLM connection flags. | Validated runtime config with secrets redacted from output. |
| Prepare Git input | Every `bridge` run | Verifies `--repo` is inside a Git repository and reads the staged diff. If the index is empty and `git.autoStageWhenNothingStaged=true`, it can run `git add -A`. | A staged diff snapshot for review and commit-message generation. |
| Commit message | Main bridge workflow only | Uses a provided message or asks the Host Agent to generate one. Validation can enforce Conventional Commits, ticket IDs, and regex rules. `--review-only` skips this step. | Final commit message, or a blocked result before review. |
| Host-Agent turn | When model text is needed and no response exists yet | Writes `turns/NNNN.request.json` and exits so the Host Agent can fill `NNNN.response.json`. | `status: "needs_host_agent"` (exit `10`). Resume with `--session`. |
| AI review | Every non-dry-run `bridge` execution | Reviews the staged diff and compares the final score with `review.threshold`. | `passed`, `blocked`, or `error` bridge output. |
| Commit | Only when review passes and `git.autoCommit=true` | Creates a local Git commit with the final commit message. | New local commit. |
| Push | Only when commit succeeds and `git.autoPush=true` | Pushes the current branch to its configured upstream. | Remote branch update, or a push-phase runtime error. |
| PR/MR auto-create | Only after a successful push when `pullRequestCreation.autoCreateAfterPush=true` | Creates or detects an existing GitHub pull request or GitLab merge request. | `pullRequestCreation` details in bridge JSON output. |
| Pass history | Only when `passHistory.enabled=true` and the configured `passHistory.writeStage` is reached | Records or upgrades the successful run to the furthest completed stage. | Local pass-history record for later reporting. |

Session progress is stored in `bridge-state.json` so resumed runs skip completed steps.

Optional follow-up commands:

```bash
smart-commit-host-agent commit-message generate --repo . --config ./smart-commit.host-agent.json --session-base /tmp/scha --output json
smart-commit-host-agent pull-request create --repo . --config ./smart-commit.host-agent.json --dry-run --output json
smart-commit-host-agent pull-request review https://github.com/org/repo/pull/123 --config ./smart-commit.host-agent.json --session-base /tmp/scha --output json
smart-commit-host-agent my-pull-request list --config ./smart-commit.host-agent.json --output json
smart-commit-host-agent my-pull-request batch-review --config ./smart-commit.host-agent.json --session-base /tmp/scha --output json
smart-commit-host-agent report generate --repo . --config ./smart-commit.host-agent.json --period weekly --output json
```

`commit-message generate` resolves only the commit-message portion of the workflow. `pull-request create` is an independent PR/MR command. `pull-request review` reviews an existing PR/MR URL and can publish comments, approve, or merge based on config. `my-pull-request list` fetches your related open PRs/MRs. `my-pull-request batch-review` lists then serially reviews them. `report generate` summarizes existing pass-history records; it is not part of every `bridge` run.

For PR/MR platform actions, set `pullRequest.authToken` in the config file (recommended: `"authToken": "env:SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN"`) or export `SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN`. Prefer that over passing `--pull-request-auth-token` on the command line.

## Prerequisites

Before you run the CLI, make sure you have:

- `Node.js >= 20`
- `git` available in your shell
- a Git repository to operate on
- staged changes for `bridge`, unless auto-stage is enabled
- a Host Agent (Cursor, Codex, …) for any command that emits `needs_host_agent`
- for PR/MR platform actions: a GitHub or GitLab token via config / env

Important command requirements:

- `smart-commit-host-agent bridge` requires `--repo`
- `smart-commit-host-agent commit-message generate` requires `--repo`
- `smart-commit-host-agent report generate` requires `--repo`
- `smart-commit-host-agent pull-request review` requires a pull request or merge request URL
- `smart-commit-host-agent my-pull-request list` requires `pullRequest.authToken`
- `smart-commit-host-agent my-pull-request batch-review` requires `pullRequest.authToken`
- `smart-commit-host-agent config resolve` does **not** require `--repo`
- `smart-commit-host-agent` rejects `--api-key`, `--base-url`, `--model`, and `--llm-provider`
- platform tokens are required **only** for commands that call GitHub/GitLab APIs: `pull-request create`, `pull-request review`, `my-pull-request list`, `my-pull-request batch-review`, and full `bridge` when it creates a PR/MR. A missing `env:` value for `pullRequest.authToken` resolves to empty instead of failing config load

## Install

Install globally:

```bash
npm install -g smart-commit-host-agent
```

Then verify:

```bash
smart-commit-host-agent --help
smart-commit-host-agent --version
```

Or use `npx` without a global install:

```bash
npx smart-commit-host-agent --help
```

If you are working from a repository checkout of this project:

```bash
npm install
npm run build
node out/cli.js --help
```

## 5-Minute Quick Start

This section is the safest first-use path for a real repository.

### 1. Create a minimal config file

Create `smart-commit.host-agent.json` (name is arbitrary):

```json
{
  "smartCommitHostAgent": {
    "review": {
      "threshold": 6,
      "language": "zh-cn"
    },
    "git": {
      "autoCommit": false,
      "autoPush": false
    }
  }
}
```

Notes:

- there is **no** `connection` block and **no** LLM API key
- keep `autoCommit` / `autoPush` false until you trust later `bridge` behavior
- built-in defaults currently enable commit, push, and PR/MR auto-create, so first-use configs should set those to `false` explicitly
- a checked-in sample lives at [`examples/config.host-agent.json`](examples/config.host-agent.json)

You do **not** need `SMART_COMMIT_API_KEY`. Export a platform token only when you will create or review PRs/MRs (step 6).

### 2. Validate the merged config first

```bash
smart-commit-host-agent config resolve --config ./smart-commit.host-agent.json
```

Why start here:

- it shows the final merged config after CLI args, env vars, file config, and defaults
- it redacts secrets in output (`pullRequest.authToken` → `[REDACTED]`)
- it catches validation problems before any turn or Git work

For a more readable terminal view:

```bash
smart-commit-host-agent config resolve --config ./smart-commit.host-agent.json --output text
```

What you should expect:

- `status: "resolved"`
- no `connection` field in the printed config
- `git.autoCommit` and `git.autoPush` are `false`

### 3. Stage a change

`bridge` works on staged content.

```bash
git add -A
git status --short
```

If nothing is staged and `autoStageWhenNothingStaged` is disabled, `bridge` will block.

### 4. Run review-only mode

This is the recommended first real run because it:

- runs review
- skips commit-message generation and validation
- returns structured output
- avoids Git side effects

```bash
smart-commit-host-agent bridge --review-only --repo . --config ./smart-commit.host-agent.json \
  --session-base /tmp/scha --output json
```

What you should expect on the first run:

- exit code `10`
- stdout JSON with `status: "needs_host_agent"`
- `sessionPath`, `requestPath`, and `turnId`

Your Host Agent (or a skill that wraps this CLI) reads the request, writes `turns/NNNN.response.json`, then resumes:

```bash
smart-commit-host-agent bridge --review-only --repo . --session <sessionPath> --output json
```

What you should expect after resume:

- `status: "passed"` if the review passes
- `status: "blocked"` if the review score is at or below `review.threshold`
- `status: "error"` if execution fails

When the review returns a numeric score, the final pass or block result is determined by comparing that score with `review.threshold`.

### 5. Optional: export a platform token for GitHub / GitLab

Needed only when you will create or review PRs/MRs. Not required for `config resolve`, `bridge --review-only`, or `commit-message generate`.

```bash
export SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN="your-gitlab-or-github-token"
```

Then add this to the config file:

```json
{
  "smartCommitHostAgent": {
    "pullRequest": {
      "provider": "gitlab",
      "authToken": "env:SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN"
    }
  }
}
```

### Shortest safe path

1. install `smart-commit-host-agent`
2. create a config **without** `connection`, with `autoCommit` / `autoPush` set to `false`
3. run `config resolve`
4. run `bridge --review-only` and complete the Host-Agent turn
5. export `SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN` only when you will create or review PRs/MRs

## Configuration Examples

### Minimal practical config

Use this when you want the smallest useful starting point:

```json
{
  "smartCommitHostAgent": {
    "review": {
      "threshold": 6,
      "language": "zh-cn"
    },
    "git": {
      "autoCommit": false,
      "autoPush": false
    }
  }
}
```

This gives you a safe review-first setup.

### Full configuration example

This is the complete `smartCommitHostAgent` surface with **built-in default values**. Use it as a field reference when skills will later create MRs and you already have a platform token: copy the block, then change only the fields you need.

These values are defaults, not a recommended first-use file. Built-in defaults currently set `git.autoCommit`, `git.autoPush`, and `pullRequestCreation.autoCreateAfterPush` to `true`. For skills and first rollout, keep those `false` (see Minimal practical config above) and set `pullRequest.authToken` to `env:SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN`.

```json
{
  "smartCommitHostAgent": {
    "review": {
      "threshold": 6,
      "language": "zh-cn",
      "maxDiffChars": 200000,
      "skill": {
        "id": "code-review",
        "path": "",
        "promptTuning": ""
      }
    },
    "commitMessage": {
      "language": "zh-cn",
      "input": "",
      "maxDiffChars": 150000,
      "structure": "subjectOnly",
      "scope": "auto",
      "autoGenerate": true,
      "hybridGenerate": false,
      "skill": {
        "id": "conventional",
        "path": "",
        "promptTuning": ""
      },
      "validation": {
        "protocol": "none",
        "pattern": "",
        "extractTicketIdFromBranch": true,
        "requireTicketIdInMessage": false
      }
    },
    "git": {
      "autoStageWhenNothingStaged": true,
      "autoCommit": true,
      "autoPush": true,
      "pushTimeoutMs": 180000
    },
    "pullRequest": {
      "provider": "auto",
      "apiBaseUrl": "",
      "authToken": ""
    },
    "pullRequestCreation": {
      "autoCreateAfterPush": true,
      "configFilePath": "",
      "targetBranch": "",
      "titlePrompt": "",
      "descriptionPrompt": "",
      "maxDiffChars": 200000,
      "assignees": [],
      "reviewers": [],
      "labels": [],
      "milestone": "",
      "draft": false,
      "removeSourceBranch": true,
      "skipBranches": ["main", "master", "develop"]
    },
    "pullRequestReview": {
      "threshold": 6,
      "autoApprove": false,
      "autoMerge": false,
      "summarySeverities": ["P0", "P1", "P2"],
      "commentSeverities": ["P0", "P1"],
      "skillPromptTuning": "",
      "skipSummaryOnPass": true,
      "skipCommentOnPass": true,
      "configFilePath": ""
    },
    "myPullRequest": {
      "listScope": "account",
      "listKinds": ["created", "assigned", "reviewer"],
      "batchReviewKinds": ["reviewer", "assigned"],
      "remoteHost": ""
    },
    "passHistory": {
      "enabled": false,
      "writeStage": "review_passed",
      "outputDirPath": "",
      "maxEntries": 3000
    },
    "reporting": {
      "language": "zh-cn",
      "weekStartsOn": "monday",
      "outputDirPath": "",
      "maxInputChars": 200000,
      "prompt": "",
      "ai": {
        "enabled": false
      }
    },
    "output": {
      "format": "json",
      "logLevel": "info"
    }
  }
}
```

Notes that are easy to misread from this dump:

- `commitMessage.skill.id` is `conventional`, but `commitMessage.validation.protocol` defaults to `none`. Set `protocol` only when the team enforces a commit style.
- `passHistory.enabled` defaults to `false`; empty `outputDirPath` falls back to the repo-local `.smart-commit-cli` directory.
- `pullRequest.authToken` defaults to empty. Platform commands still need a token; local-only commands do not.

### Using a smart-commit-cli config file

Rename the root key to `smartCommitHostAgent`. A `smartCommitCli` root key is rejected. If `connection` is still present inside `smartCommitHostAgent`, it is stripped.

Do not pass LLM CLI flags; they are rejected.

## Choose The Right Command

Instead of memorizing every command, use this section by intent.

### I want to verify my config

```bash
smart-commit-host-agent config resolve --config ./smart-commit.host-agent.json
```

Use this when you want to:

- inspect the merged config
- confirm env var resolution
- catch validation issues early

### I want review only, with no commit or push

```bash
smart-commit-host-agent bridge --review-only --repo . --config ./smart-commit.host-agent.json \
  --session-base /tmp/scha --output json
```

Use this when you want to:

- review staged changes
- skip commit-message generation, validation, local commit, and push
- onboard a skill without touching Git history

If you want the main bridge workflow to still generate or validate the commit message but stop before creating a local commit, use `--no-commit` instead.

### I want a full review / commit / PR flow

```bash
smart-commit-host-agent bridge --repo . --config ./smart-commit.host-agent.json \
  --session-base /tmp/scha --output json
```

Use this only when your config intentionally allows the desired side effects.

Depending on config, the CLI may:

- review only
- review and create a local commit
- review, commit, push, and create a PR/MR

### I want to generate a commit message

```bash
smart-commit-host-agent commit-message generate --repo . --config ./smart-commit.host-agent.json \
  --session-base /tmp/scha --output json
```

Pass `--commit-message "feat: example"` as provided input. With `hybridGenerate=false` (the default), that validates the message and skips the Host-Agent turn; with `hybridGenerate=true`, the draft is refined in a turn.

### I want to create a PR or MR

```bash
smart-commit-host-agent pull-request create --repo . --config ./smart-commit.host-agent.json \
  --title "Add feature" --description "## Summary" --dry-run --output json
```

Use `--dry-run` to generate PR/MR content without creating it. Provide `pullRequest.authToken` in the config file or `SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN`.

### I want to review an existing PR or MR

```bash
smart-commit-host-agent pull-request review https://github.com/org/repo/pull/123 \
  --repo . --config ./smart-commit.host-agent.json --session-base /tmp/scha --output json
```

This command reads the remote PR/MR, runs review against its diff, and can publish inline comments, approve, or merge when configured. Use `--dry-run` to keep it read-only for platform actions. Auth comes from `pullRequest.authToken` in config or `SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN`.

### I want to list my related open PRs or MRs

```bash
smart-commit-host-agent my-pull-request list --config ./smart-commit.host-agent.json --output json
```

This command fetches open PRs/MRs related to the authenticated account. It requires `pullRequest.authToken` but does not need a Host-Agent turn. Use `--my-pull-request-list-scope workspace` with repeated `--repo` paths to scope the list to specific local repositories. With `listScope=account` and `myPullRequest.remoteHost` set, the command does not require a local git repository.

### I want to batch-review my related open PRs or MRs

```bash
smart-commit-host-agent my-pull-request batch-review --config ./smart-commit.host-agent.json \
  --session-base /tmp/scha --output json
```

This command lists PRs/MRs using `myPullRequest.batchReviewKinds`, then serially runs full review for each item. When a turn needs a Host Agent response, it exits `needs_host_agent` (10); resume with `--session`. Exit `2` when any review does not pass.

### I want to generate a report

```bash
smart-commit-host-agent report generate --repo . --config ./smart-commit.host-agent.json --period weekly
```

Supported `--period` values:

- `daily`
- `yesterday`
- `weekly`
- `last-week`
- `monthly`
- `last-month`
- `quarterly`
- `last-quarter`
- `yearly`

If you omit `--period`, it defaults to `weekly`. If `passHistory.enabled=true`, successful bridge runs are written locally and later summarized into a Markdown report.

Optional AI-enhanced reporting (Host-Agent turn, then local fallback on non-turn failures):

```bash
smart-commit-host-agent report generate --repo . --config ./smart-commit.host-agent.json \
  --period weekly --report-ai --session-base /tmp/scha --output json
```

### I want machine-readable schemas

```bash
smart-commit-host-agent schema print --target config-file
```

Supported schema targets:

- `config-file`
- `config-resolve`
- `bridge`
- `commit-message-generate`
- `report-generate`
- `pull-request-create`
- `pull-request-review`
- `my-pull-request-batch-review`

Schemas never include LLM `connection` fields.

## Core Commands Reference

### Help and version

```bash
smart-commit-host-agent --help
smart-commit-host-agent --version
```

### Resolve config

```bash
smart-commit-host-agent config resolve --config ./smart-commit.host-agent.json
smart-commit-host-agent config resolve --config ./smart-commit.host-agent.json --output text
```

### Review-only bridge

```bash
smart-commit-host-agent bridge --review-only --repo . --session-base /tmp/scha --output json
smart-commit-host-agent bridge --review-only --repo . --session /path/to/session --output json
```

### Full bridge execution

```bash
smart-commit-host-agent bridge --repo . --config ./smart-commit.host-agent.json --session-base /tmp/scha --output json
```

### Generate a commit message

```bash
smart-commit-host-agent commit-message generate --repo . --session-base /tmp/scha --output json
smart-commit-host-agent commit-message generate --repo . --commit-message "feat: example" --output json
```

### Create a PR or MR

```bash
smart-commit-host-agent pull-request create --repo . --config ./smart-commit.host-agent.json \
  --title "Add feature" --description "## Summary" --output json
```

Requires `pullRequest.authToken` and a forge `origin` remote. Dry-run skips the create POST.

### Review an existing PR or MR

```bash
smart-commit-host-agent pull-request review https://gitlab.com/group/project/-/merge_requests/7 \
  --repo . --config ./smart-commit.host-agent.json --session-base /tmp/scha --output json
```

### List my related open PRs or MRs

```bash
smart-commit-host-agent my-pull-request list \
  --pull-request-auth-token "$SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN" \
  --pull-request-provider gitlab \
  --my-pull-request-list-scope account \
  --my-pull-request-remote-host gitlab.example.com \
  --output json
```

### Batch-review my related open PRs or MRs

```bash
smart-commit-host-agent my-pull-request batch-review \
  --pull-request-auth-token "$SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN" \
  --pull-request-provider github \
  --my-pull-request-list-scope account \
  --my-pull-request-remote-host github.com \
  --session-base /tmp/scha \
  --output json
```

### Generate a report

```bash
smart-commit-host-agent report generate --repo . --config ./smart-commit.host-agent.json --period weekly --output json
```

### Print a schema

```bash
smart-commit-host-agent schema print --target bridge
```

## Output Modes

Default output is machine-facing JSON:

```bash
smart-commit-host-agent bridge --review-only --repo . --output json
```

For a human-friendly terminal summary of `config resolve`:

```bash
smart-commit-host-agent config resolve --config ./smart-commit.host-agent.json --output text
```

Recommended usage:

- use `json` for skills, hooks, and scripts
- use `text` for local debugging of `config resolve` when supported

For machine integrations, the usual pattern is:

- call `smart-commit-host-agent <command> --output json`
- consume stdout as JSON
- branch on `status` and `error.code`
- when `status` is `needs_host_agent`, fill the response file and re-run with `--session`

## Exit Codes

These are especially useful in shell scripts and agent skill loops.

| Code | Meaning |
| --- | --- |
| `0` | Success |
| `2` | Blocked (review did not pass the threshold, or a preflight block) |
| `3` | Config / input error |
| `4` | Runtime error |
| `10` | `needs_host_agent` — Host Agent must write a turn response and resume with `--session` |

Typical interpretation:

- `config resolve`: `0` success, `3` invalid config / missing env / rejected LLM flags
- `bridge --review-only`: `10` waiting for review turn, `0` passed, `2` blocked (score at/below threshold)
- `bridge` (full): same turn exits, plus commit/push outcomes
- `commit-message generate` / `pull-request create` / `pull-request review`: `10` waiting for turn, `0` success, `2` blocked where applicable
- `my-pull-request batch-review`: `10` waiting for a turn, `0` when every item passed, `2` when any review did not pass

## Configuration Rules

Config precedence from high to low:

1. CLI arguments
2. environment variables
3. `smartCommitHostAgent` in a JSON config file (`smartCommitCli` is rejected; `connection` is stripped if present inside `smartCommitHostAgent`)
4. built-in defaults

Special rules:

- values like `env:SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN` are resolved from the current process environment after merge and before validation
- secrets should use `env:VAR_NAME` references in the config file
- LLM connection flags are not supported and will fail fast
- explicit `--config <path>` is required to load a file (there is no silent auto-discovery of a default filename)

## CLI Flags Reference

Common flags:

| Flag | Purpose |
| --- | --- |
| `--config <path>` | Config file path |
| `--repo <path>` | Git repository path |
| `--output <json\|text>` | Output mode |
| `--session <path>` | Resume an existing turn session |
| `--session-base <dir>` | Base directory when creating a new session |
| `--dry-run` | Skip Git / create side effects where supported |
| `--commit-message <text>` | Provided commit message (bridge / commit-message generate) |
| `--title` / `--description` | Provided PR/MR content (pull-request create) |
| `--fixture-pr <path>` | Optional offline fixture for pull-request review |
| `--no-commit` / `--no-push` | Override git autoCommit / autoPush (bridge) |
| `--period` / `--start-date` / `--end-date` | Report window (`report generate`) |
| `--report-ai` | Enable AI-enhanced reporting via a Host-Agent turn |
| `--pull-request-auth-token <token>` | Override `pullRequest.authToken` (create / review / list) |
| `--pull-request-provider <auto\|github\|gitlab>` | Override `pullRequest.provider` (create / review / list) |
| `--pull-request-api-base-url <url>` | Override `pullRequest.apiBaseUrl` (create / review / list) |
| `--my-pull-request-list-scope <account\|workspace>` | List scope for `my-pull-request list` |
| `--my-pull-request-list-kinds <created,assigned,reviewer>` | Comma-separated kinds for `my-pull-request list` |
| `--my-pull-request-batch-review-kinds <created,assigned,reviewer>` | Kinds for `my-pull-request batch-review` |
| `--my-pull-request-remote-host <host>` | Account-list host; with account scope, skips git remotes |

Rejected flags (always):

| Flag | Reason |
| --- | --- |
| `--api-key` / `--api-key=…` | No LLM connection transport |
| `--base-url` / `--base-url=…` | No LLM connection transport |
| `--model` / `--model=…` | No LLM connection transport |
| `--llm-provider` / `--llm-provider=…` | No LLM connection transport |

## Environment Variables Reference

| Variable | Used for |
| --- | --- |
| `SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN` | Typical `pullRequest.authToken: "env:SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN"`; missing/empty resolves to `""` |
| Any other `env:NAME` referenced in config | Resolved at load time; missing/empty values fail validation |

Not used:

| Variable | Notes |
| --- | --- |
| `SMART_COMMIT_API_KEY` | Not used by this package (ignored if set) |

## Reporting

If `passHistory.enabled=true`, successful bridge runs are written to local history and can be summarized later:

```bash
smart-commit-host-agent report generate --repo . --config ./smart-commit.host-agent.json --period weekly
```

`passHistory.writeStage` controls the earliest successful stage that can create a record. Once a record exists, later successful stages update the same pass-history entry, so `eventType` always reflects the furthest successful stage reached by that run.

- `review_passed` writes as soon as review passes. If that same run later reaches a local commit or push, the existing record is upgraded instead of duplicated.
- `commit_completed` waits until the local commit succeeds. If a later push succeeds, that same record is upgraded to `commit_push_completed`.
- `commit_push_completed` writes only after both the local commit and the push succeed.

Report summaries use these records to show:

- total successful review passes
- local commit completions
- commit and push completions

## How The Host Agent Fills AI Text

When a command needs model text, it writes a turn request and exits. A Host Agent (or a skill wrapping this CLI) fills the matching response file, then the same command is re-run with `--session`.

Session layout:

```text
<sessionDir>/
  session.json
  turns/
    0001.request.json
    0001.response.json
    …
```

Request (CLI → Host Agent) includes `turnId`, `kind`, `purpose`, `messages`, `responseSchema`, and `attempt`.

Response (Host Agent → CLI):

```json
{
  "turnId": "0001",
  "content": "model output as a string"
}
```

`turnId` must match the request. Skill loop:

```text
loop:
  run smart-commit-host-agent <cmd> [--session …] --output json
  if needs_host_agent → fill response → continue with --session
  else → finish (passed | blocked | error | …)
```

`host-agent probe` is a diagnostic for this loop, not a user workflow. See [`docs/integrations.md`](https://cdn.jsdelivr.net/npm/smart-commit-host-agent/docs/integrations.md) for skill and script patterns.

## Common First-Time Mistakes

### I exported `SMART_COMMIT_API_KEY` but nothing changed

Expected. This package does not read LLM API keys. Remove any `connection` block and stop passing LLM flags.

### `pullRequest.authToken is required …`

The current command talks to GitHub/GitLab. Export `SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN` (or whatever `env:VAR` your config names). Local-only commands (`config resolve`, `bridge --review-only`, `commit-message generate`) do not need this token; a missing `env:` value resolves to empty instead of failing config load.

### `pullRequest.authToken references missing or empty environment variable …`

This now applies to **other** `env:VAR` fields, not `pullRequest.authToken`. Export the referenced variable, or remove the `env:` reference from config.

### `smart-commit-host-agent does not use LLM connection flags`

You passed `--api-key`, `--base-url`, `--model`, or `--llm-provider`. Drop those flags.

### I accidentally enabled auto-commit or auto-push too early

Built-in defaults currently enable `git.autoCommit`, `git.autoPush`, and `pullRequestCreation.autoCreateAfterPush`. For first rollout, set them to `false` in config, then use `bridge --review-only`.

### I expected report generate to call an LLM HTTP API

`report generate` uses local Markdown rendering by default. When `reporting.ai.enabled` is true (or `--report-ai`), it emits a host-agent `complete` turn with `purpose: "report"` — resume with `--session` after writing the turn response. There is no LLM HTTP path.

### I expected the config file to be auto-loaded

File-backed resolve requires an explicit `--config <path>`.

## Recommended First Rollout

For a new team, skill, or repository, use this order:

1. create a minimal or safer team config **without** `connection`
2. run `smart-commit-host-agent config resolve`
3. run `smart-commit-host-agent bridge --review-only` and complete the Host-Agent turn
4. embed the same review-only command into your skill
5. enable pass history
6. add reporting
7. optionally dry-run `pull-request review` against a test PR/MR
8. only then consider automatic commit, push, approval, or merge

This sequence keeps the first rollout safe while still letting you validate the entire workflow.

## Where To Go Deeper

For deeper detail after the first successful run (links use jsDelivr so they work from the published package, not a public GitHub tree, and browsers get `charset=utf-8`):

- getting started from source: [`docs/getting-started.md`](https://cdn.jsdelivr.net/npm/smart-commit-host-agent/docs/getting-started.md)
- configuration details: [`docs/configuration.md`](https://cdn.jsdelivr.net/npm/smart-commit-host-agent/docs/configuration.md)
- integration patterns: [`docs/integrations.md`](https://cdn.jsdelivr.net/npm/smart-commit-host-agent/docs/integrations.md)
- machine-facing contracts: [`docs/contracts.md`](https://cdn.jsdelivr.net/npm/smart-commit-host-agent/docs/contracts.md)

Changelog: [`CHANGELOG.md`](https://cdn.jsdelivr.net/npm/smart-commit-host-agent/CHANGELOG.md)

## Related: smart-commit-copilot-cli

Most users only need this package. If you already use (or are comparing against) [`smart-commit-copilot-cli`](https://www.npmjs.com/package/smart-commit-copilot-cli) — a sibling CLI that calls an LLM HTTP API with your own `connection` credentials — here is how they differ:

| Topic | `smart-commit-host-agent` | `smart-commit-copilot-cli` |
| --- | --- | --- |
| Model source | Host Agent turn protocol | LLM HTTP API via `connection.*` |
| LLM API key | Not used | Required for AI-backed commands |
| Config root key | `smartCommitHostAgent` only (`smartCommitCli` is rejected; `connection` is stripped if present inside it) | `smartCommitCli` |
| Binary | `smart-commit-host-agent` | `smart-commit` |
| Typical consumer | Agent skills (e.g. Cursor / Codex) | Terminal, hooks, CI, scripts |

Git / review threshold / PR token behavior aims to stay aligned with the CLI version pinned as `peerReference.cliVersion` in `package.json`.