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, 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:

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:

npm install -g smart-commit-host-agent

Then verify:

smart-commit-host-agent --help
smart-commit-host-agent --version

Or use npx without a global install:

npx smart-commit-host-agent --help

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

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):

{
  "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

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

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:

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.

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

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:

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.

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

Then add this to the config file:

{
  "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:

{
  "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.

{
  "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

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

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

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

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

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

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

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

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

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):

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

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

smart-commit-host-agent --help
smart-commit-host-agent --version

Resolve config

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

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

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

Generate a commit message

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

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

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

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

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

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

Print a schema

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

Output Modes

Default output is machine-facing JSON:

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

For a human-friendly terminal summary of config resolve:

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:

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:

<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):

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

turnId must match the request. Skill loop:

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 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
• configuration details: docs/configuration.md
• integration patterns: docs/integrations.md
• machine-facing contracts: docs/contracts.md

Changelog: 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 — 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.