code-converge (also known as review-fixes and improver) is a Go CLI that closes the agent-development loop: it asks an agent to review the current repository, fixes the findings, commits and publishes the result, and makes sure required CI is green when CI applies.
code-converge supports Codex as its only agent. The command is intended to be run from the repository that should be reviewed.
code-converge -h and code-converge --help are equivalent, write a concise command and global-option reference to stdout, and exit 0 without loading configuration or starting an update or review workflow. Root help lists the config and update commands, all supported global options, and points to this README for the complete configuration reference. Use code-converge config --help for the configuration command syntax, and code-converge update --help for update syntax including --yes / -y.
usage: code-converge [flags] [config]
Commands:
config Show effective configuration and its sources.
update [--yes|-y] Check for and install a newer release.
Global options:
Output:
--log-format Workflow output format: human or kv.
...
See README.md for the full configuration reference.
flowchart TD
A["code-converge"] --> B[Review]
B --> C{Findings?}
C -- yes --> E{Fix budget remains?}
E -- yes --> D[Fix findings]
E -- no --> X1[Exit 1]
D --> K["Commit local checkpoint when fixes changed the clean worktree"]
K --> B
C -- no --> N{Unpublished changes or local checkpoint?}
N -- no --> X0[Exit 0: no-op]
N -- yes --> F[Commit, push, create change request if needed, check applicable CI]
F --> G{Result}
G -- all done; CI green or N/A --> X0[Exit 0]
G -- published; CI red --> J{CI-recovery budget remains?}
J -- yes --> H[Fix CI]
J -- no --> X3[Exit 3]
H --> I{Fix succeeded?}
I -- yes --> B
I -- no --> X3[Exit 3]
G -- other failure --> X2[Exit 2]
┌─────────────────────────────────────────────────────────────────────┐
│ code-converge CLI │
└─────────────────────────────────────────────────────────────────────┘
args ──► parse flags ──► load config ──┬── config cmd? ──► print & exit 0
│
▼
┌──────────────────┐
│ run_started │
└────────┬─────────┘
│
┌─────────────────────┘
│ phase=1, cycle=1, fixes=0, recoveries=0
│
▼
╔═══════════════════╗ ◄──────────────────────────────┐
║ REVIEW STAGE ║ │
║ ║ │
║ codex exec ║ │
║ schema + snapshot ║ │
╚════════╤══════════╝ │
│ │
▼ │
┌────────────────┐ │
│ Read strict JSON│ │
│ final file only │ │
└───────┬────────┘ │
│ │
┌────────┴────────┐ │
│ │ │
▼ ▼ │
┌─────────┐ ┌───────────┐ │
│ CLEAN │ │ FINDINGS │ │
│ │ │ │ │
│ counts │ │ counts │ │
│ = 0 │ │ P0..P3 │ │
└────┬────┘ └─────┬─────┘ │
│ │ │
│ fixes < max_cycles? │
│ ┌────┴────┐ │
│ yes no ──► exit 1 (findings_remaining) │
│ │ │
│ ▼ │
│ ╔══════════════════════╗ │
│ ║ FIX-FINDINGS ║ │
│ ║ ║ │
│ ║ codex exec - ║ │
│ ║ stdin: ║ │
│ ║ fix_prompt + ║ │
│ ║ "\n\n" + ║ │
│ ║ review_report ║ │
│ ╚═════════╤═══════════╝ │
│ │ │
│ fixes++ │
│ cycle++ │
│ │ │
│ └───────────────────────────────────────────┘
│
▼
┌──────────────────────┐
│ Check Git status and │
│ run-local checkpoint │
│ state │
└───────┬─────────┬────┘
│ yes │ no
▼ └────────► run_completed success, exit 0
╔══════════════════════════════════╗
║ PUBLISH (host git/gh processes) ║
║ commit → direct-ref push → PR ║
╚═══════════════╤══════════════════╝
│ published HEAD SHA
▼
╔══════════════════════════════════╗
║ CI (host GitHub check-run poll) ║
║ exact SHA; deadline = ci-timeout ║
╚═════╤═══════════╤═══════════╤══════╝
│ │ │
green/N/A failed timeout/error
│ │ │
│ Fix CI? └──► exit 2 (ci_timeout/operational_failure)
│ │
│ yes ──► Codex Fix CI → review phase + 1
│ no ──► exit 3 (ci_failure)
▼
run_completed success, exit 0
Key points:
- Review — resolves the intended pull-request base and runs one schema-constrained
codex execagainst a private merge-base-to-worktree snapshot, including committed, staged, unstaged and untracked changes. Only the final-message file is classified; terminal stdout/stderr are not review data. - Fix —
codex exec -, stdin = fix-prompt + full review report. The stateless remediation session receives the findings it must address. - Publish and CI — host-process
git/ghorchestration, with CI pinned to the published SHA. - CI recovery — a deterministically failed applicable check starts Fix CI, resets the fix cycle, and restarts from Review. A timeout never starts Fix CI.
- Budget —
max-cyclescounts only fix attempts, not the initial review. - Fail closed — unknown output ≠ clean; mixed output = error.
code-converge runs non-interactive codex exec --output-schema <schema> --output-last-message <message> - in the current directory. By default it resolves one review base in this order: an explicit review-base setting, the base of one open pull request for the current branch and its configured push/provider repository (or origin when Git's usual push-remote settings are absent), branch.<current>.gh-merge-base, then exactly one remote default-branch ref. Provider discovery verifies the PR head repository and branch against the current branch's provider identity, resolves the PR base branch against one remote-tracking ref and compares its commit SHA with the provider's advertised base SHA. If that uniquely selected remote-tracking ref is stale, Code-Converge fetches only the advertised base branch into that ref, then verifies the SHA again; a failed or still-mismatched refresh is an actionable operational error. It never fetches for an explicit review-base, an ambiguous/local-only candidate, or any other discovery source. The resolved base SHA is pinned for every review in the run. Code-Converge computes the merge-base and prepares a private Git index from that tree plus the current worktree; this includes committed, staged, unstaged and untracked changes without modifying the real index or worktree. A review-only Git helper applies that index only after confirming that a Git command targets the reviewed repository, while absolute Git paths, repository-creation commands, and commands targeting another repository retain their normal index. Code-Converge forces its wrapper-first PATH and neutral shell-startup settings through the per-review Codex shell policy, disables login-shell startup, and removes inherited Git repository/index/config transports and exported shell functions for that review. This prevents startup files or caller state from reordering PATH, replacing git, or redirecting Git away from the intended repository/index. The helper reads its private configuration from a sidecar file, so an include_only policy that allows PATH needs no extra helper variables; GIT_INDEX_FILE is not exported to Codex. All paths recorded in that sidecar must be valid UTF-8; unsupported Linux byte paths fail before the helper is created rather than being replaced during JSON encoding. Reviewed-root commands that explicitly enable Git split-index are rejected before they can create shared-index state outside the disposable command index. The review instruction compares git diff --cached from the computed merge base through the scoped helper. Ambiguous, missing, or unrefreshable candidates fail with a diagnostic before Codex starts. Provider discovery through gh is optional; unavailable gh or authentication falls through to local Git sources. No PR or other remote mutation occurs.
--review-base <ref>, CODE_CONVERGE_REVIEW_BASE and .code-converge/review-base explicitly select the base using the normal configuration precedence. A branch already merged into the selected base has no committed delta but still reviews worktree changes; a fully clean run follows the existing clean/no-change path. It uses the model and reasoning effort resolved from the selected mode and any explicit stage overrides.
Ordinary code review remains the default. Select at most one explicit review mode: --review-prompt-file <path> reads a regular Markdown file from an absolute or current-directory-relative path; --review-prompt <name> reads only .code-converge/<name>.md (names contain letters, digits, _ or -); and --document-review reviews only changed .md files in the same private snapshot, excluding memory-bank/prompts/**. The document mode uses .code-converge/default.md when it exists and otherwise uses its built-in prompt. Missing, unreadable, non-Markdown, invalid or conflicting selections exit 2 without fallback. If no eligible documents changed, no Codex review is started. Document mode is review-only: after a clean scoped review it exits successfully without publication or CI, so unrelated worktree changes cannot be shipped by the whole-worktree publication path.
Run code-converge init-document-review-prompt to write the built-in document prompt to .code-converge/default.md; an existing file is preserved unless --force is supplied. In document mode, --document-fix-prompt-file <path> selects a Markdown fix instruction. It requires --document-review and conflicts with --fix-prompt-file; without it, the built-in document-fix instruction is used.
The review adapter supplies a strict JSON Schema and, after a zero Codex exit, reads only the file named by --output-last-message. The response must contain exactly findings, overall_correctness, overall_explanation, and overall_confidence_score; every finding must contain title, body, confidence_score, numeric priority, and code_location in the documented nested shape. An empty findings array is the only clean result. Plain text, terminal stdout/stderr, duplicate or unknown fields, invalid priorities, missing/empty/malformed files, and non-zero command exits cannot be classified as clean and produce operational exit 2. Codex compatibility is capability-based: the configured CLI must support exec, --output-schema, and --output-last-message; unsupported invocations fail closed without falling back to terminal parsing.
For metrics, schema priorities are normalized as follows: 0 (P0) → critical, 1 (P1) → high, 2 (P2) → medium, and 3 (P3) → low. Any other priority makes the response invalid. The public unknown counter remains present for event-schema compatibility and is zero for accepted structured responses. findings_total must equal the sum of all five counters.
When the review has findings, code-converge detects whether the Git worktree is clean before considering an automatic checkpoint, then starts a fresh Codex session with the configured fix-findings prompt followed by the complete classified review report. This preserves remediation for the documented staged, unstaged and untracked review scope. A dirty baseline safely skips checkpointing so it cannot capture pre-existing user work. By default, the prompt is:
fix findings
The default fast profile uses gpt-5.6-luna with reasoning effort medium. Before and after the agent runs, code-converge records HEAD and checks Git status. If the fix changed an initially clean worktree, it stages the changes and creates one local commit with the stable message chore: checkpoint review fixes; it never pushes this checkpoint. A commit made directly by the agent is also detected as a local checkpoint, even when the worktree is clean, so a later clean review still reaches publication. A dirty pre-fix worktree continues through remediation but skips the automatic checkpoint and reports that reason if the budget is later exhausted. A no-change fix attempts no empty commit. A status, HEAD, staging, commit, branch, or commit-ID failure is operational (exit 2) and the workflow does not start another review. After a successful checkpoint decision or skip, the workflow returns to Review.
max-cycles is the maximum number of fix-findings attempts in one review phase; its built-in default is 10 and it must be non-negative. The initial review does not consume this budget. After the final allowed fix attempt, code-converge always performs one verification review. If that review still has findings, code-converge reports that the limit has been reached, that clean-review publication was not reached, and the latest local checkpoint state before exiting with code 1. A failed fix-findings command is an operational failure and exits with code 2.
After a clean review, Code Converge—not Codex—performs publication. It creates a commit only when the run began with a clean worktree; pre-existing dirty content is never committed automatically. It uses a direct Git refspec push, so a local remote-tracking-ref refresh cannot make a successful remote publication look failed. It then reuses exactly one matching open pull request or creates one; ambiguous identity is operational failure.
Code Converge polls every page of GitHub check-runs for the exact published HEAD SHA. The applicable set is the returned check-runs: no returned runs is skipped; success, skipped, and neutral terminal conclusions are accepted; the first other completed conclusion is failed; pending runs continue waiting. --ci-timeout / CODE_CONVERGE_CI_TIMEOUT / .code-converge/ci-timeout use normal precedence and default to 60m. Timeout is an explicit operational ci_timeout outcome (exit 2), not failed CI and never invokes Fix CI. Transient provider failures are retried inside the same deadline; authentication and authorization failures are operational.
When deterministic CI polling reports a failed applicable check, code-converge starts Codex with the configured CI-fix prompt. This stage is skipped when no applicable check-run exists. Its built-in prompt is:
Исправь CI
The default fast profile uses gpt-5.6-luna with reasoning effort medium for this stage.
If the agent completes successfully, the entire workflow begins again with a new Review phase and a fresh max-cycles budget, rather than only re-checking CI. The run also has a separate non-negative max-ci-recoveries budget, default 3, to prevent an endless clean-review/failing-CI loop. If the CI-fix command fails, or CI is still red after all recovery attempts have been used, code-converge exits with code 3.
| Code | Meaning |
|---|---|
0 | The review is clean and either no staged, unstaged or untracked changes exist, or changes are committed and pushed; a change request exists if needed; required CI is green or CI is not applicable. update also returns 0 when the installed version is current or the user declines the update. |
1 | Review findings remain after the configured maximum number of fix-findings attempts. The terminal record states that publication was not reached and gives the latest local checkpoint outcome. |
2 | An operational/configuration failure occurred, review output was ambiguous, fix-findings failed, publication/provider failure occurred, or CI timed out. update uses it for unsupported hosts, invalid release metadata, download/checksum failures, or replacement/permission failures. |
3 | The CI-fix stage failed or the maximum number of CI-recovery attempts was exhausted. |
During a workflow run, code-converge writes operational progress to standard output in one deterministically selected format: human or kv. The built-in default is human; select kv explicitly for machine-readable automation. TTY detection never selects the semantic format. Raw Codex stdout and stderr are captured by the process boundary and are never review-result data or workflow stdout; stderr may enrich the diagnostic for a failed Codex process. Unless disabled, private diagnostic session records capture those invocation details locally; they are not event-stream records.
kv preserves the stable machine-readable stream. Every stage transition and meaningful step is exactly one newline-terminated record.
Every record starts with ts and event. Stage-scoped records also include stage; review-loop records include review_phase and cycle. Completion records include their result and elapsed stage time as defined below.
Records use stable key=value fields separated by one ASCII space. Field names contain only lowercase ASCII letters, digits, and underscores. Values must not contain whitespace, =, or newlines; free-form text is written to stderr instead. ts is UTC RFC 3339, durations are integer milliseconds, and unknown/optional fields are omitted only when the event contract says they are inapplicable.
review_phase starts at 1 and increments after every successful CI-fix stage. cycle starts at 1 in each review phase. A fix-findings stage uses the same cycle number as the review that produced its input; the next review increments cycle. Therefore, with max-cycles=10, the last allowed fix uses cycle=10 and its mandatory verification review uses cycle=11. A new review phase resets cycle to 1.
The required event catalog is:
| Event | Required event-specific fields |
|---|---|
run_started | No fields beyond ts and event. |
stage_started | stage, model, reasoning_effort; also review_phase and cycle for review and fix-findings, and review_phase for fix-ci. |
review_completed | stage=review, model, reasoning_effort, review_phase, cycle, status=clean|findings|scope_empty|failed, and duration_ms. A classified result (clean, findings, or scope_empty) also requires review_scope=branch_and_worktree, review_base (resolved commit SHA), review_merge_base and review_base_source=explicit|open_pr|branch_merge_base|remote_default; clean and findings include all findings counters. scope_empty is emitted when document review has no eligible Markdown changes and terminates successfully without publication. On command or classification failure these fields and counters are omitted. This is the review stage's sole completion record. |
stage_completed | stage=fix-findings|publish|ci|fix-ci, status, and duration_ms; Codex-backed stages also include model and reasoning effort. ci status is success, skipped, failed, or timeout; a CI timeout additionally has timeout_ms, the configured deadline. |
step_completed | stage=publish, step=commit|push|change_request, and status=success|skipped|failed|unknown; CI emits its own stage=ci step with success|skipped|failed|timeout. |
run_completed | status=success|scope_empty|findings_remaining|operational_failure|ci_timeout|ci_failure|cancelled, exit_code, and total_duration_ms. scope_empty has exit_code=0 and means document review found no eligible Markdown changes; publication and CI are not reached. cancelled always has exit_code=130; ci_timeout has exit_code=2. For findings_remaining, also checkpoint_status=committed_local|no_changes|not_attempted; committed_local additionally requires percent-encoded checkpoint_branch and checkpoint_commit, while not_attempted requires checkpoint_reason=fix_budget_exhausted|pre_existing_changes. |
For example:
ts=2026-07-21T10:04:05Z event=stage_started stage=review model=gpt-5.6-sol reasoning_effort=medium review_phase=1 cycle=2
ts=2026-07-21T10:06:18Z event=review_completed stage=review model=gpt-5.6-sol reasoning_effort=medium review_phase=1 cycle=2 status=findings findings_total=3 findings_critical=0 findings_high=1 findings_medium=2 findings_low=0 findings_unknown=0 duration_ms=133000
ts=2026-07-21T10:06:19Z event=stage_started stage=fix-findings model=gpt-5.6-luna reasoning_effort=medium review_phase=1 cycle=2
ts=2026-07-21T10:10:42Z event=stage_completed stage=fix-findings model=gpt-5.6-luna reasoning_effort=medium review_phase=1 cycle=2 status=success duration_ms=263000
ts=2026-07-21T10:12:00Z event=step_completed stage=publish step=change_request status=skipped
Every successfully classified review logs findings_total plus findings_critical, findings_high, findings_medium, findings_low, and findings_unknown. Every counter is present even when its value is 0. If the review command fails or its report is ambiguous, status=failed is emitted with duration_ms; finding counters are omitted because no reliable review result exists.
The review-completion record is emitted even when there are no findings, for example:
ts=2026-07-21T10:12:09Z event=review_completed stage=review model=gpt-5.6-sol reasoning_effort=medium review_phase=1 cycle=3 status=clean findings_total=0 findings_critical=0 findings_high=0 findings_medium=0 findings_low=0 findings_unknown=0 duration_ms=87000
This makes the trend across cycles directly measurable without requiring it to be monotonic: the findings_* fields show how the number and severity change, while duration_ms measures the cost of each review, fix, publication, CI, and CI-fix stage. run_completed contains status, exit_code, and total_duration_ms.
Human is the built-in format for concise operator output. Every permanent line starts with local HH:MM:SS; retryable stage lines then include [attempt/max] [model/reasoning-effort] with no separator before the message. The overall terminal line has no attempt or model because it does not belong to a single stage. Human lines omit raw event keys and the redundant run_started record. A findings summary always shows P0, P1 and P2, while P3 and Unknown appear only when non-zero. Durations below one minute use seconds rounded to a tenth with a trailing .0 removed; longer durations use rounded whole seconds in compact h m s form. Select --log-format=kv when an integration requires the machine-readable event stream.
When diagnostic session logging is enabled and its record directory has been created, human output first writes exactly one permanent path handoff such as 22:14:05 Session log: /Users/me/.code-converge/session-logs/session-.... It contains no session content. kv output and --no-session-log omit this line.
| Workflow result | Human output |
|---|---|
| Review starts in the initial phase (non-TTY) | 22:14:05 [1/10] [gpt-5.6-sol/high] Review started |
| Review starts after the first CI recovery (non-TTY) | 22:14:05 [1/10] [gpt-5.6-sol/high] Review started (phase 2 after CI recovery 1) |
| Review is clean | 22:14:05 [2/10] [gpt-5.6-sol/high] Review: clean (1m 27s) |
| Review has findings | 22:14:05 [2/10] [gpt-5.6-sol/high] Review: 3 findings [P0:0; P1:1; P2:2] (2m 13s) |
| Review fails | 22:14:05 [2/10] [gpt-5.6-sol/high] Review failed (2m 13s) |
| Fix findings starts / succeeds / fails | 22:14:05 [2/10] [gpt-5.6-luna/medium] Fixing findings / 22:14:05 [2/10] [gpt-5.6-luna/medium] Findings fixed (4m 23s) / 22:14:05 [2/10] [gpt-5.6-luna/medium] Fixing findings failed (4m 23s) |
| Publication starts / steps / succeeds | 22:14:05 Publishing / 22:14:05 Push: done / 22:14:05 Published (42s) |
| CI starts / succeeds / is skipped | 22:14:05 Waiting for CI / 22:14:05 CI passed (3m 2s) / 22:14:05 CI skipped: no applicable checks (0s) |
| CI fails / times out | 22:14:05 CI failed (42s) / 22:14:05 CI timed out (60m) |
| CI recovery starts / succeeds / fails | 22:14:05 [1/3] [agent-default/agent-default] CI recovery / 22:14:05 [1/3] [agent-default/agent-default] CI recovery fixed (1m 8s) / 22:14:05 [1/3] [agent-default/agent-default] CI recovery failed (1m 8s) |
| Run succeeds | 22:14:05 Done (8m 45s) |
| Findings remain | 22:14:05 Stopped: review findings remain (8m 45s, exit 1) |
| Operational failure | 22:14:05 Failed due to an operational error (8m 45s, exit 2) |
Interrupted with Ctrl-C | 22:14:05 Cancelled (8m 45s, exit 130) |
| CI remains red | 22:14:05 Stopped: CI is still failing (8m 45s, exit 3) |
A findings summary always includes the total. It always renders P0, P1 and P2, then appends non-zero P3 and Unknown counts. Successful terminal lines omit exit 0; non-success terminal lines retain exit codes 1, 2, 3, and 130 as applicable.
In human mode on an interactive stdout terminal, each Codex-backed stage displays one in-place elapsed-time line such as 22:14:05 [1/10] [gpt-5.6-sol/high] Reviewing... 1m 24s. The timer changes once per second while a soft color highlight travels across the fully colored line and returns at a 10-frame-per-second refresh rate. The live line replaces the permanent stage-start line in an interactive terminal, so the output is not duplicated. The line is cleared before permanent stdout or diagnostic stderr output.
--color=never or the presence of NO_COLOR disables shimmer while retaining the elapsed line. auto uses true color when advertised by COLORTERM, ANSI-256 when advertised by TERM, basic magenta/cyan otherwise, and no color for unknown or dumb terminals.
Non-TTY output has no implicit liveness and never contains ANSI controls. In human mode, an explicit positive heartbeat replaces transient animation and emits newline-safe records at the requested interval:
22:14:05 [1/10] [gpt-5.6-sol/high] Review still running (30s)
22:15:05 [1/10] [gpt-5.6-sol/high] Review still running (1m)
Heartbeat is disabled by default, accepts 0 or a Go duration of at least 1s, and is rejected with log-format=kv. Liveness stops and joins before stage completion, failure, cancellation, or later output; a liveness write error becomes operational failure.
In human mode, when both standard input and standard output are terminals and TERM is neither empty nor dumb, Code-Converge prints Interactive view available: press i to open once at startup and accepts one-key terminal input. Press i during a workflow to toggle a split view without interrupting the active Codex process. Ctrl-C always retains its normal interrupt behavior: it cancels the workflow, terminates its active subprocess group, reports Cancelled, and exits 130 rather than reporting an operational failure. The upper pane retains the workflow log; the lower pane shows arriving stdout and stderr from the active agent. Stderr lines are marked [stderr].
The view uses the terminal alternate screen and restores it when closed, on workflow completion, cancellation, interruption, setup failure, or panic unwinding. Each pane retains its most recent 2,000 logical lines; long lines wrap to the current terminal width. Tab selects a pane, arrow keys and Page Up/Down scroll it, and End returns it to the live tail. A view opened before an agent starts says No active agent output; completion leaves the final stream visible until the next agent stage.
Agent output is sanitized before rendering: terminal controls are removed, invalid UTF-8 is rendered as replacement characters, and raw process output never enters workflow stdout. If the terminal is ineligible or raw-mode setup fails, no view is started and the existing human output continues unchanged. Non-interactive output and kv retain their existing contracts and never require a TTY.
code-converge config is a separate human-readable command and is not part of the workflow event stream.
Every option can be supplied in four places: a command-line flag, an environment variable, project YAML, or user YAML.
Resolution order is highest to lowest priority:
- Command-line flags
- Project configuration in
<git-root>/.code-converge/config.yaml - User configuration in
~/.code-converge/config.yaml - Environment variables
- Built-in defaults
mode resolves through this order and defaults to fast. Each explicit per-stage model or reasoning-effort setting from any of the first four sources overrides the selected profile; source precedence is then applied among those explicit settings. An unset stage setting inherits from the effective mode.
This matches the configuration approach of start-issue: a project may pin shared behavior, a user may set personal defaults, and a one-off invocation can override either.
Prompts are file-backed, so they can be reviewed and versioned with project configuration. An absent project/user prompt file means that source has no value and resolution continues. An explicitly supplied CLI or environment path that does not exist is a configuration error and exits 2. Relative CLI/environment paths are resolved from the current directory; project and user prompt files are resolved inside their respective configuration directories.
The fast and best modes select these operative stage profiles. fast is the built-in mode. Code-Converge passes both resolved values to Codex as -c model=<model> and -c model_reasoning_effort=<effort> for every stage.
| Stage | Fast | Best | Escalate to gpt-5.6-sol when |
|---|---|---|---|
| Review | gpt-5.6-terra, medium | gpt-5.6-sol, high | Not applicable: independent quality judgment is the stage's primary purpose. |
| Fix findings | gpt-5.6-luna, medium | gpt-5.6-terra, high | Findings involve architecture, security, migrations, concurrency, or several connected modules. |
| Fix CI | gpt-5.6-luna, medium | gpt-5.6-terra, high | The cause is not localized by logs, spans multiple components, or persists after a repair. |
config.yaml is the only file-based configuration source. It is a strict, flat YAML mapping: unknown, duplicate, nested, malformed, and invalid values are rejected. Legacy per-setting files are ignored without migration or fallback. Prompt values remain file references; relative paths resolve from the directory containing the YAML file.
| Option | Flag | Environment variable | YAML key | Default |
|---|---|---|---|---|
| Workflow log format | --log-format | CODE_CONVERGE_LOG_FORMAT | log-format | human |
| Human liveness heartbeat | --heartbeat | CODE_CONVERGE_HEARTBEAT | heartbeat | 0 (disabled) |
| Interactive shimmer color | --color | CODE_CONVERGE_COLOR | color | auto |
| Mode | --mode | CODE_CONVERGE_MODE | mode | fast |
| Maximum fix-findings attempts per review phase | --max-cycles | CODE_CONVERGE_MAX_CYCLES | max-cycles | 10 |
| Maximum CI recoveries | --max-ci-recoveries | CODE_CONVERGE_MAX_CI_RECOVERIES | max-ci-recoveries | 3 |
| CI wait timeout | --ci-timeout | CODE_CONVERGE_CI_TIMEOUT | ci-timeout | 60m |
| Review model | --review-model | CODE_CONVERGE_REVIEW_MODEL | review-model | selected profile |
| Review reasoning effort | --review-reasoning-effort | CODE_CONVERGE_REVIEW_REASONING_EFFORT | review-reasoning-effort | selected profile |
| Fix-findings model | --fix-model | CODE_CONVERGE_FIX_MODEL | fix-model | selected profile |
| Fix-findings reasoning effort | --fix-reasoning-effort | CODE_CONVERGE_FIX_REASONING_EFFORT | fix-reasoning-effort | selected profile |
| Fix-findings prompt | --fix-prompt-file | CODE_CONVERGE_FIX_PROMPT_FILE | fix-prompt-file | fix findings |
| CI-fix model | --ci-fix-model | CODE_CONVERGE_CI_FIX_MODEL | ci-fix-model | selected profile |
| CI-fix reasoning effort | --ci-fix-reasoning-effort | CODE_CONVERGE_CI_FIX_REASONING_EFFORT | ci-fix-reasoning-effort | selected profile |
| CI-fix prompt | --ci-fix-prompt-file | CODE_CONVERGE_CI_FIX_PROMPT_FILE | ci-fix-prompt-file | Исправь CI |
| Review base override | --review-base | CODE_CONVERGE_REVIEW_BASE | review-base | discover intended base |
| Diagnostic session-log directory | --session-log-dir | CODE_CONVERGE_SESSION_LOG_DIR | session-log-dir | ~/.code-converge/session-logs |
| Diagnostic session-log retention | --session-log-retention | CODE_CONVERGE_SESSION_LOG_RETENTION | session-log-retention | 24h |
| Disable diagnostic logging for this run | --no-session-log | — | — | disabled only when flag supplied |
--finalize-model, --finalize-reasoning-effort, and --finalize-prompt-file, their CODE_CONVERGE_FINALIZE_* environment variables, and their YAML keys were removed in this release because Codex no longer performs publication or CI polling. Obsolete environment settings and YAML keys cause actionable configuration errors.
For example, a team can commit one project configuration document and keep prompt content alongside it:
.code-converge/
├── config.yaml
└── prompts/
├── fix-findings.md
└── fix-ci.md
# <git-root>/.code-converge/config.yamlmode: bestmax-cycles: 3ci-timeout: 45mreview-base: mainfix-prompt-file: prompts/fix-findings.mdci-fix-prompt-file: prompts/fix-ci.mdThe same schema in ~/.code-converge/config.yaml sets user-level defaults. Environment variables are particularly useful in CI or temporary shell sessions:
CODE_CONVERGE_MAX_CYCLES=3 \
CODE_CONVERGE_REVIEW_MODEL=gpt-5.6-sol \
code-convergesession-log-dir must resolve to an absolute path (a leading ~ expands to the user home); session-log-retention is a Go duration of at least 1s. 0 and negative values are invalid; use --no-session-log for a no-artifact run. At the start of an enabled run, Code-Converge creates an owner-only directory where the platform permits, then best-effort removes only expired, completed direct session-* child directories from that configured root; incomplete or unreadable sessions are retained so a concurrent active run cannot be removed. Cleanup, create, write and permission failures are diagnostics on stderr and do not alter an otherwise valid workflow result. Session records include redacted command/stdin/stdout/stderr data, but may still contain sensitive repository content, prompts, paths and agent output. They never include process environment values; known credential-bearing argument/text forms, including complete keyed values and separate credential-flag values, are replaced with [REDACTED]. Use --no-session-log when such local retention is not acceptable.
Use the dedicated configuration command to inspect the active configuration:
code-converge configIt prints the effective mode and every setting with its effective value and source. Profile-derived settings identify the selected profile; explicit settings identify their winning source. Whenever an effective value differs from the global fast built-in baseline, that baseline is shown too. This makes overrides and configuration precedence explicit without starting a review.
Example shape of the output:
mode: fast (built-in default)
review-model: gpt-5.6-terra (fast profile)
max-cycles: 3 (project; built-in: 10)
fix-prompt: .code-converge/fix-findings.md (project; built-in: "fix findings")
- Go runtime is not required to run a released binary; it is required to build from source.
codexmust be installed, authenticated, and available onPATHwhen runningcode-converge.- The authenticated account must have access to every model selected by the effective profile and any explicit stage overrides.
- The target directory must be a Git repository.
git,gh, and GitHub credentials must be available to the Code Converge host process for deterministic publication and CI polling.
The supported first-release targets are macOS and Linux on AMD64 and ARM64. Released archives contain a single statically built code-converge binary and are accompanied by SHA256SUMS; a Go runtime is not required after installation.
Check the installed binary version with:
code-converge --versionIt prints code-converge vX.Y.Z for a release binary.
On macOS or Linux AMD64/ARM64, an installed release binary can safely update itself from the latest stable GitHub Release:
code-converge updateThe command compares the running semantic version with the latest release. When a newer compatible release exists, it prints the target version and release notes (or the release URL), then prompts Install update? [y/N]: . Only the exact replies y and yes proceed; all other input leaves the current executable unchanged. An already-current binary and a declined update exit 0.
For unattended use, skip confirmation without reading standard input:
code-converge update --yes
# short form
code-converge update -yBefore replacing the binary, update downloads the matching archive and SHA256SUMS from the release, verifies the archive checksum, and stages the replacement beside the running executable. It atomically replaces only that executable after all checks pass. Status, release notes and the confirmation prompt go to stdout; diagnostics go to stderr. Unsupported platforms, malformed metadata, download/checksum failures and permission/replacement failures exit 2 and leave the original executable byte-for-byte unchanged.
The process needs write permission to the directory containing the currently running binary. If an update fails, keep using the existing binary and check the stderr diagnostic; recover by correcting the permission/network problem and rerunning update, or reinstall a known release with the one-line installer below. The command does not use package managers, prereleases, downgrades, background checks or automatic updates at normal startup.
Build the current platform binary with Go 1.21.13 or newer:
make buildBuild the complete deterministic artifact matrix:
VERSION=0.1.0 make distVersioned archives and SHA256SUMS are published through GitHub Releases. Verify the checksum, extract the archive for the target platform, and copy code-converge to a directory on PATH, for example /usr/local/bin or a user-owned bin directory. No package-manager, registry, or signing channel is currently promised.
Maintainers record user-facing changes under ## [Unreleased] in CHANGELOG.md, then prepare a semantic release locally:
make release-patch # or release-minor / release-major
git push origin master --follow-tagsThe preparation command requires a clean worktree, updates VERSION and the changelog, runs verification, creates the release commit, and creates an annotated vX.Y.Z tag. Pushing the tag triggers CI, which rebuilds and verifies the complete artifact matrix before publishing the GitHub Release.
Download and install the latest release on macOS or Linux with one command (the archive is selected from the current OS and CPU architecture):
curl -fsSL https://raw.githubusercontent.com/dapi/code-converge/master/scripts/install.sh | shThe installer verifies SHA256SUMS before placing code-converge in ~/.local/bin. Add that directory to PATH if needed. For a pinned release, set CODE_CONVERGE_VERSION:
curl -fsSL https://raw.githubusercontent.com/dapi/code-converge/master/scripts/install.sh | CODE_CONVERGE_VERSION=0.1.0 shThe installer is intentionally limited to macOS and Linux on AMD64/ARM64 and does not require Go.
Start with memory-bank/README.md for project context and governance. The import/adaptation plan and its acceptance criteria are recorded in .protocols/memory-bank-integration.md; those documents refer back here instead of duplicating the public CLI contract.