github.com/kardolus/chatgpt-cli

v1.11.0

A feature-packed release: native function calling, JSON / structured output, accurate token counting, and a round of reliability hardening — all backward compatible.

✨ New features

• Native function calling — with --tools (plus --mcp <endpoint>), the model can now call your MCP server's tools autonomously. The CLI lists the server's tools (tools/list), advertises them to the model, dispatches each requested call (tools/call), and feeds the results back until the model produces a final answer. A big step up from the one-shot --mcp-tool injection.
• JSON mode / structured output — --json for plain JSON output (shorthand for --response-format json_object), or --response-format '<schema>' / --response-format @schema.json to constrain output to a JSON Schema.
• Accurate token counting — context-window truncation now uses real tiktoken BPE counts for OpenAI models (embedded vocab, no runtime download), with a graceful fallback to the previous heuristic for non-OpenAI providers.

🛡️ Reliability

• Automatic retries with backoff — transient connection errors, 429, and 5xx are retried; a Retry-After header is honored, otherwise jittered exponential backoff. Tunable via the new max_retries and retry_base_delay_ms settings.
• Graceful Ctrl-C — pressing Ctrl-C now cleanly cancels the in-flight request, stream, or agent loop instead of hard-killing the process. In interactive mode it aborts the current response and keeps the session alive.
• Streaming errors surfaced — a dropped connection mid-stream is now reported instead of silently returning a truncated response.
• Fail-loud config — an invalid numeric/boolean environment override now errors clearly instead of silently defaulting to zero.

⚙️ New config keys

response_format, tools, max_tool_calls, max_retries, retry_base_delay_ms — see the README configuration table for details.

🔧 Under the hood

• cmd/chatgpt/main.go was split into cohesive files and unit-test coverage was expanded (extracted CLI helpers, agent/tools).
• No new user-facing dependencies of note; every change ships CI-green (unit + integration + contract).

How to update

You can update chatgpt-cli in one of two ways:

Option 1: Update via Homebrew (macOS / Linux)

If you installed via Homebrew, update to v1.11.0 with:

brew upgrade chatgpt-cli

Confirm the installed version afterward:

chatgpt --version

Option 2: Direct download (prebuilt binaries)

If you installed using a standalone binary, download the v1.11.0 binary for your OS/architecture from the releases page and replace your existing binary:

1. Download the correct binary for your OS (macOS, Linux, Windows, FreeBSD).
2. Replace the existing binary in your PATH.
3. On macOS/Linux, make it executable:

chmod +x /path/to/chatgpt

1. Verify:

chatgpt --version

Release Version: v1.10.12

New Features

• Added Atlas Cloud provider configuration documentation
  • The README now includes setup instructions for using Atlas Cloud (OpenAI-compatible endpoint) with an example config.yaml profile and ATLASCLOUD_API_KEY environment variable usage.
  • Code reference: README.md

Improvements

• MCP: support for stateless servers (optional session ID)

  • The MCP client no longer fails when an initialize response omits the mcp-session-id header. In this case, the client proceeds without session state and simply omits Mcp-Session-Id on subsequent calls.
  • This aligns behavior with the streamable-HTTP spec where the session ID is optional.
  • Code reference: api/client/mcp.go, api/client/mcp_test.go, README.md

• Security hardening for agent shell steps

  • Added a defense-in-depth policy check that denies shell step arguments containing common shell expansion patterns:
    • Unix-like expansions: $VAR, ${VAR}, $(cmd)
    • Backtick command substitution: `cmd`
    • Windows-style expansions: %VAR%
  • This helps reduce risk when file access is restricted to the configured work directory.
  • Code reference: agent/core/policy.go, agent/core/policy_test.go

• CI and linting modernization

  • Updated GitHub Actions to install Go explicitly and moved the linter action to golangci-lint-action@v9 (golangci-lint v2) to support the repository’s Go 1.25 target.
  • Added a repository-wide golangci-lint v2 configuration that restores prior lint behavior (keeps exclusion presets and limits staticcheck checks to avoid newly-enforced style/quickfix rules).
  • Code reference: .github/workflows/test.yml, .golangci.yml

• Toolchain and dependency updates

  • Upgraded the module to Go 1.25.0 and bumped key dependencies (notably gomega and zap) along with related indirect dependency updates.
  • Code reference: go.mod, go.sum

Bug Fixes

• Fixed MCP failures against stateless endpoints
  • Previously, the MCP client errored if initialize succeeded but returned no mcp-session-id. This has been corrected to treat such servers as stateless rather than failing.
  • Code reference: api/client/mcp.go, api/client/mcp_test.go

Other Changes

• Release runbook added

  • Added a detailed release process document covering prerequisites, tagging, building binaries, publishing GitHub releases, and updating the Homebrew tap.
  • Code reference: CLAUDE.md

• Test script quality-of-life improvement

  • The “TODO scan” in the test runner now ignores Markdown files to prevent documentation text from failing CI/release checks.
  • Code reference: scripts/all-tests.sh

Upgrade Notes (How to Update)

• Homebrew (recommended):

  brew update
  brew upgrade chatgpt-cli

• Direct download (prebuilt binaries):
  • Download the appropriate chatgpt-<os>-<arch> binary from the GitHub Release assets for v1.10.12 (e.g., chatgpt-darwin-arm64, chatgpt-linux-amd64, chatgpt-windows-386, etc.).
  • Replace your existing installed binary with the downloaded one (ensure it is executable on Unix-like systems).

New Features

• Configurable HTTP client timeout (http_timeout)
  • Added a new configuration option to control the HTTP client timeout (in seconds), allowing better support for slow or local models and environments with variable latency.
  • Supports setting the timeout to 0 for no timeout.
  • Code references:
    • config/config.go (new HTTPTimeout field)
    • cmd/chatgpt/main.go (new config wiring and set-http-timeout support)
    • api/http/http.go (HTTP client now uses configured timeout)
    • README.md (documented new setting)

Improvements

• HTTP client behavior is now configurable rather than fixed

  • Replaces the previously hardcoded timeout with a value driven by user configuration, improving flexibility across different runtime environments.
  • Code reference: api/http/http.go

• Expanded test coverage for HTTP configuration

  • Added tests to verify timeout behavior (configured timeout and default behavior).
  • Code reference: api/http/http_test.go

Bug Fixes

• No user-facing bug fixes identified beyond the shift from a hardcoded HTTP timeout to a configurable value.

Other Changes

• Documentation update
  • Added http_timeout to the configuration/environment variable documentation table.
  • Code reference: README.md

Upgrade Notes

• Homebrew (recommended):
  • Run: brew upgrade chatgpt-cli
• Direct download:
  • Download the prebuilt binaries for your specific OS from the project’s release artifacts and replace your existing chatgpt executable.

This release focuses on safer persistence and file permissions, more reliable config writes, and bounded agent transcript/prompt logging to prevent unbounded memory/log growth while improving debuggability.

New Features

• Capped in-memory transcript and prompt history (with truncation banner)

  • Introduced a new TranscriptBuffer utility to store agent transcripts and prompt history with a strict maximum size and a visible …(truncated) banner when older content is dropped.
  • Integrated into BaseAgent as Transcript and PromptHistory, enabled by default with conservative limits and configurable via:
    • core.WithTranscriptMaxBytes(n)
    • core.WithPromptHistoryMaxBytes(n)
  • Code references:
    • agent/core/transcript_buffer.go (new)
    • agent/core/base_agent.go

• Cross-platform config write locking

  • Added an OS-specific file lock implementation to prevent concurrent config writes from corrupting the config file.
  • Code references:
    • config/file_lock_unix.go (new)
    • config/file_lock_windows.go (new)
    • config/store.go

• Secure API key file reader

  • Centralized API key file loading with validation:
    • must be a regular file
    • must not be empty
    • size capped at 10KB
    • path is cleaned
  • Code references:
    • config/read_api_key_file.go (new)
    • cmd/chatgpt/main.go

Improvements

• Agent runs now capture structured transcripts for easier debugging

  • Both Plan-and-Execute and ReAct agents now:
    • reset transcript/history at the start of each run
    • record key lifecycle events (goal, plan steps, prompts, raw LLM output, actions, outcomes, final result)
  • This provides consistent, machine-readable traces while keeping memory usage bounded.
  • Code references:
    • agent/planexec/plan_execute_agent.go
    • agent/react/react_agent.go

• HTTP client now uses a default timeout

  • Adds a 60-second timeout to avoid indefinite hangs on network calls.
  • Maintains SkipTLSVerify support while reusing a cloned default transport.
  • Code reference: api/http/http.go

• Safer “workdir escape” detection

  • Workdir and resolved target paths now evaluate symlinks before containment checks, improving correctness when symlinks are involved.
  • Code reference: agent/core/policy.go

Bug Fixes

• Prevent transcript/prompt history accumulation across agent runs

  • Agents explicitly reset buffers at the start of RunAgentGoal, eliminating “leftover” content leaking into subsequent runs.
  • Tests added to prevent regressions.
  • Code references:
    • agent/planexec/plan_execute_agent.go, agent/planexec/plan_execute_agent_test.go
    • agent/react/react_agent.go, agent/react/react_agent_test.go

• Hardened config persistence to reduce risk of partial/corrupted writes

  • Config writes are now:
    • protected by a lock
    • written via an atomic temp-file + rename strategy
    • synced to disk (best-effort)
    • permissions preserved when possible
  • Code reference: config/store.go

Other Changes

• Tighter default filesystem permissions for sensitive data

  • Log dir permissions: 0700 (was 0755)
    • agent/core/log.go
  • Config file writes: 0600 (was 0644)
    • cmd/chatgpt/main.go (config save)
    • config/store.go (atomic write defaults/preserve)
  • CLI interactive history file: 0600 (was 0644)
    • cmd/chatgpt/utils/utils.go
  • Stored conversation history directory and files:
    • directory 0700 and files 0600
    • history/store.go

• Reduced plan logging output

  • Removed writing the raw plan JSON artifact (keeps normalized plan logging).
  • Code reference: agent/planexec/plan.go

• Dependency updates

  • Updated testing/dependency versions (e.g., gomega, ginkgo, and related golang.org/x/* tooling updates reflected in go.sum).
  • Code references: go.mod, go.sum

Upgrade Notes

• Homebrew (recommended):

  • Run:

    brew upgrade chatgpt-cli

• Direct download:

  • Download the prebuilt binary for your specific OS/architecture from the project’s release artifacts, then replace your existing chatgpt-cli binary with the new one (ensure it is executable and on your PATH).

New Features:

• Enhanced Diff Application with Fuzzy Matching:
  • Introduced a new feature that improves how diffs are applied by allowing for "fuzzy" matches around preferred indexes. This feature aims to increase the robustness of applying patches where multiple matching contexts exist.
  • Code reference: unified_diff.go, unified_diff_test.go

Improvements:

• Improved Error Messaging:

  • Updated error messages to include more contextual information, such as diff line numbers. This enhancement helps in diagnosing issues more effectively.
  • Code reference: unified_diff.go

• Refactor and Cleanup:

  • Code refactoring to improve readability and maintainability, focusing on the diff utilities module.
  • Code reference: unified_diff.go, unified_diff_test.go

Bug Fixes:

• Patch Context Matching Issues:
  • Resolved bugs where patch application would fail due to context mismatches. Now, the application logic correctly identifies and matches the context even in complex scenarios.
  • Code reference: unified_diff.go, unified_diff_test.go

Other Changes:

• Test Suite Expansion:

  • Added numerous test cases to thoroughly validate the new fuzzy diff application logic, ensuring correctness across various scenarios.
  • Code reference: unified_diff_test.go

• Removed Obsolete Assets:

  • Deleted redundant agent.gif files from the repository to reduce clutter.
  • Code reference: Removed agent.gif

Upgrade Notes:

• The release version v1.10.9 introduces improvements and features requiring a system update. You can update to the latest version using one of the following methods:
  • Run brew upgrade chatgpt-cli, if you are using Homebrew.
  • Alternatively, download the binaries directly from our official releases page for your specific operating system.

We hope you enjoy these improvements and appreciate your support and feedback as we continue to enhance our software.

New Features

• Enhanced ReAct Agent Logic:
  • Implemented improved iterative reasoning and action mechanisms.
  • The agent now recovers more gracefully from models producing invalid JSON in response.
  • Enhanced in-band recovery and error messaging for better user interaction.
  • Code reference: agent/react/react_agent.go

Improvements

• Code Refactoring:

  • The codebase has been reorganized for greater modularity, splitting different logical parts into dedicated packages (such as core, planexec, react, and tools).
  • Clear separation of concerns, improving both readability and maintainability.
  • Code reference: Multiple files under agent/, tools/, and core/ directories.

• Policy Enforcement Updates:

  • Improved safety checks within the agent policy model.
  • Enhanced context-specific guidance to prevent undesired actions.
  • Code reference: agent/core/policy.go

• Improved Budget Handling:

  • Better error handling when budget constraints are exceeded, providing clearer feedback to users.
  • More robust handling of LLM token budgets, making iterative tasks more predictable.
  • Code reference: agent/core/budget.go

Bug Fixes

• Tool Integration:

  • Fixed issues where file operations might not respect path constraints properly.
  • Addressed shell tool command handling errors, particularly with variadic arguments.
  • Code reference: Various files within tools/

• Template Processing:

  • Resolved issues with Go template rendering within agent steps, reducing the occurrence of template syntax errors.
  • Code reference: agent/planexec/template_step.go

• Compatibility and Resilience:

  • Corrected JSON parsing logic to handle output wrapped in markdown code fences correctly.
  • Enhanced compatibility with different JSON action types generated by the model.
  • Code reference: agent/react/react_agent.go

Other Changes

• Testing Enhancements:
  • Expanded unit test coverage to validate new behaviors and ensure system robustness against unexpected input.
  • Increased resilience against external dependencies changes.
  • Code reference: Various test files under agent/planexec/ and agent/react/

Upgrade Notes

To upgrade to the latest version of chatgpt-cli, you may use the following methods:

• Using Homebrew:

  brew upgrade chatgpt-cli

• Direct Download:
  • Download the appropriate binaries for your operating system from the releases page of the project.

Ensure to back up any configuration files or essential data before you upgrade, especially if you have custom configurations in place.

New Features

• Patch and Replace File Operations: Introduced PatchFile and ReplaceBytesInFile methods on the Files interface to allow more efficient in-place file modifications without needing to read the entire content.
  • PatchFile Method: Applies a unified diff to a file.
  • ReplaceBytesInFile Method: Replaces byte patterns with new data in a file, supporting controlled occurrences.

Improvements

• Unified Diff Parsing: Enhanced diff parsing capability with robust handling of edge cases and strict adherence to unified diff standards.
• Error Handling in Operations: Improved error messages and handling, particularly in PatchFile and ReplaceBytesInFile, making the operations more resilient and informative when issues are encountered.
• Logging Improvements: Adjustments to log file creation and opening process to truncate files instead of appending to existing ones, leading to cleaner log management.

Bug Fixes

• Policy Enforcement Adjustments: Correct handling of file operation permissions in policies, fixing issues where certain operations could be allowed or denied incorrectly based on configuration.
• OutcomeError Handling: Modified behavior to surface errors within the system through OutcomeError, allowing agents to notice and react to changes or anomalies during execution.

Other Changes

• Integration and Unit Test Expansions: Added comprehensive tests for newly implemented file operations ensuring reliability and correctness through various scenarios.
• Refactorings in react_agent.go: Cleaned up the logic for running actions, ensuring better readability and maintainability.
• Runtime Enhancements: Minor runtime structures and logic updates for more efficient running of agent goals and budget management.

Upgrade Notes

To upgrade to v1.10.7, you can use Brew or directly download binaries:

• Via Homebrew: Execute brew upgrade chatgpt-cli in your terminal.
• For a direct download, obtain the binaries specific to your operating system from the official release page.

Ensure your configuration settings in config.yaml are updated according to any newly introduced options if applicable.

New Features

• Enhanced Logging System:
  • Introduced the ability to sync logs manually for both human-readable and debug logs using new sync functions.
  • Modified logger output to better distinguish between transcript (plain text) and debug (JSONL) formats.
  • Code references: agent/log.go, agent/agent.go

Improvements

• Code Refactoring for Logging:

  • Adapted agent.go to utilize zapcore.NewTee for simultaneous logging to the terminal and to a transcript file, enhancing the readability and accuracy of the logs during operations.
  • Improved the efficiency of log management by ensuring that syncing operations are embedded within the logger's base options.
  • Code references: cmd/chatgpt/main.go, agent/log.go

• Documentation Update:

  • Expanded the AGENTS.md file with clearer instructions and more detailed project layout explanations to aid developers in contributing effectively.
  • Code reference: AGENTS.md

Bug Fixes

• Testing and Mocks Update:
  • Rectified unnecessary clock expectations in test cases, ensuring a more accurate and simplified test environment.
  • Code references: agent/react_agent_test.go

Other Changes

• Testing Enhancements:
  • Upgraded test routines by integrating sclevine/spec and gomega conventions, safeguarding that both unit and integration tests conform to a standard format.
  • Code references: agent/react_agent_test.go

Upgrade Notes

To upgrade to the latest version of the chatgpt-cli, follow these steps:

• If you have Homebrew installed, run the command: brew upgrade chatgpt-cli
• Alternatively, you can directly download the precompiled binaries appropriate for your operating system from our release page.

This new release continues to strengthen our commitment to delivering a robust and efficient tool, enhancing the user experience with each update. We hope you enjoy the new features and improvements. If you have any feedback or run into any issues, please feel free to reach out to us.

Thank you for using chatgpt-cli!

New Features

• Repetition Guard for ReAct Agent:
  • Introduced a new mechanism to prevent repetitive actions in the ReAct agent, enhancing decision-making and reducing redundant command executions.
  • Code reference: agent/react_agent.go

Improvements

• Enhanced Action Type Handling:
  • Improved the handling of action types in the ReAct agent, now supporting shorthand notation for tools like ‘file’, ‘shell’, and ‘llm’.
  • This update makes the agent more robust and ensures that incorrect shorthand usage leads to actionable errors.
  • Code reference: agent/react_agent.go

Bug Fixes

• Fixed Validation for Inconsistent Shorthand Usage:
  • Corrected an issue where using inconsistent shorthand action types with tools would not validate correctly, potentially leading to execution errors.
  • Code reference: agent/react_agent.go

Other Changes

• Documentation Overhaul:

  • The AGENTS.md document has been significantly condensed and rewritten to provide clear guidance and structured information for both contributors and users regarding how to work with the CLI application.
  • Code reference: AGENTS.md

• Testing Enhancements:

  • Added comprehensive tests for new functionality in the ReAct agent to ensure that changes adhere to expected standards and behaviors.
  • Code reference: agent/react_agent_test.go

Upgrade Notes

To upgrade to version v1.10.5, you can use the following methods:

• With Homebrew:

  brew upgrade chatgpt-cli
  

• Direct Download:
  Visit the release page to download binaries for your specific operating system.

This release introduces several new features, optimizations, bug fixes, and additional changes aimed at enhancing the overall functionality and usability of the project. Below is a summary of the key updates included in this version.

New Features

• AGENTS.md Documentation:

  • Added a comprehensive AGENTS.md file outlining the architecture and usage of the ChatGPT CLI, including experimental agent modes like ReAct and Plan/Execute.
  • This document serves as an orientation guide for automated agents and contributors, detailing the repository's structure and core functionalities.

• Proof of Concept Image:

  • A new image (poc.png) has been added to the cmd/chatgpt/resources/ directory to support visualization needs for development and promotional purposes.

Improvements

• ReAct Agent Logic Refinement:
  • Enhanced the parsing logic of the ReAct agent to improve JSON object extraction, ensuring more reliable interpretation of responses.
  • Updated CRITICAL RULES for JSON response consistency, emphasizing single-action responses and clear formatting guidelines.

Bug Fixes

• JSON Parsing in ReAct Agent:
  • Fixed a bug in the ReAct agent that incorrectly parsed JSON strings, leading to potential errors during agent operation. Refined the error handling to provide more descriptive feedback when parsing fails.

Other Changes

• Refactored Agent Execution Flow:

  • Streamlined the code execution path within the runAgent function by removing redundant logger initializations and improving the layout of debugging logs.

• Testing Adjustments:

  • Updated unit tests (react_agent_test.go) to ensure they align with new parsing error messages, strengthening overall test coverage and reliability.

Upgrade Notes

To upgrade to this release:

• Use Homebrew: Run brew upgrade chatgpt-cli in your terminal.
• Alternatively, download the latest binaries directly for your operating system from the releases page.

This release focuses on improving the robustness of the ChatGPT CLI, offering clearer integration pathways for new users and contributors while maintaining backward compatibility. For further details, please refer to the updated documentation provided in this release.