ggcode Python wrapper
ggcode on PyPI bootstraps the native ggcode terminal agent from GitHub Releases.
When the bootstrap runs, it installs the real binary into a stable CLI location instead of keeping it in a wrapper-managed cache:
- macOS / Linux: prefers
/usr/local/bin, falls back to~/.local/bin - Windows: prefers
%USERPROFILE%\\AppData\\Local\\Programs\\ggcode\\bin, falls back to%USERPROFILE%\\.local\\bin
If that directory is not already on PATH, the bootstrap updates your PATH configuration and asks
you to reopen the terminal so future ggcode launches resolve directly to the native binary.
Install
pip install ggcode
Then run:
ggcode
If you ever need to rerun the bootstrap flow explicitly, you can also use:
ggcode-bootstrap
What it does
- Detects your operating system and CPU architecture
- Downloads the latest matching
ggcodearchive from GitHub Releases - Verifies the archive against
checksums.txt - Installs the real binary into a stable PATH location
- Updates PATH so future
ggcodelaunches bypass the Python wrapper
Pin a specific ggcode release
By default, the wrapper always resolves the latest ggcode release.
To force a specific release, set GGCODE_INSTALL_VERSION:
GGCODE_INSTALL_VERSION=vX.Y.Z ggcode
or:
GGCODE_INSTALL_VERSION=X.Y.Z ggcode
Other install methods
Homebrew (macOS / Linux)
brew tap topcheer/ggcode
brew trust topcheer/ggcode
brew install ggcode # CLI
brew install ggcode-desktop # Desktop (Linux)
brew install --cask ggcode-desktop # Desktop (macOS DMG)
winget (Windows)
winget install --id gg.ai.ggcode-cli # CLI
winget install --id gg.ai.ggcode-desktop # Desktop
Native release packages
Download directly from GitHub Releases:
| Platform | Format | Install command |
|---|---|---|
| macOS | .pkg |
sudo installer -pkg ./ggcode_*_darwin_universal.pkg -target / |
| Windows | .msi |
msiexec /i .\ggcode_*_windows_x64.msi |
| Debian / Ubuntu | .deb |
sudo dpkg -i ./ggcode_*_linux_*.deb |
| Fedora / RHEL | .rpm |
sudo rpm -i ./ggcode-*-1.*.rpm |
| Alpine | .apk |
sudo apk add --allow-untrusted ./ggcode-*-r1.*.apk |
| Arch Linux | .pkg.tar.zst |
sudo pacman -U ./ggcode-*-1-*.pkg.tar.zst |
What is ggcode?
ggcode is a terminal-native AI coding agent — not a browser wrapper, not a VS Code extension. It runs entirely in your terminal with a polished TUI:
- Multi-provider LLM support — OpenAI, Anthropic, Google Gemini, GitHub Copilot, DeepSeek, and more
- Five permission modes — supervised, plan, auto, bypass, autopilot — you decide how much autonomy the agent gets
- LSP integration — go-to-definition, references, rename, diagnostics, code actions via your language server
- MCP tools — connect external tool servers (browser, databases, APIs) seamlessly
- Sub-agents — spawn parallel workers for research, coding, and testing tasks
- Harness workflows — structured engineering pipelines with git worktrees, review, and promotion
- IM gateway — connect QQ, Telegram, Discord, Slack, DingTalk, or Feishu for remote coding
- Bilingual UI — full English and Chinese support
- Session persistence — resume past sessions with
ggcode --resume - File checkpoints — undo bad edits instantly without git
Supported platforms
- macOS
- Linux
- Windows
Supported architectures:
- x86_64 / amd64
- arm64
Desktop Application
ggcode also ships as a native desktop GUI application with visual chat, IM integration, and tool approval dialogs.
Download from GitHub Releases:
| Platform | Asset |
|---|---|
| macOS (Universal) | ggcode-desktop_*_darwin_universal.dmg |
| Windows | ggcode-desktop_*_windows_amd64.exe |
Project links
- GitHub Releases: https://github.com/topcheer/ggcode/releases
- Desktop app downloads: available on the same releases page
- Discord community: https://discord.gg/F2v4mJmfG
- Repository: https://github.com/topcheer/ggcode
- Issues: https://github.com/topcheer/ggcode/issues
1 maintainer
Metadata
1 maintainer
Release files for ggcode 1.3.158
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| ggcode-1.3.158.tar.gz | 8.2 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ggcode-1.3.158-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 15.7 kB
Release files / ggcode-1.3.158.tar.gz
| Download URL | ggcode-1.3.158.tar.gz |
|---|---|
| Size | 8.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4ac58c9f301a6eadfef7187eedae2075f49698e874943528dcb6e56e0bb218d0
|
|
BLAKE2b-256 checksum How to use checksums |
2b4dc89744f108ba3111ea16d65ca74118d4a780fa325bd83413a54c605f8b09
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 17, 2026.
Transparency logRelease files / ggcode-1.3.158-py3-none-any.whl
| Download URL | ggcode-1.3.158-py3-none-any.whl |
|---|---|
| Size | 7.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
05df56527c1da3c4c25c8933124ca6fad73206dc1b3de457e52f41ac5366996f
|
|
BLAKE2b-256 checksum How to use checksums |
af6ceee925f968ca77eb24beb4812e8461c64dc016559310427b17caf04b4e1f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 17, 2026.
Transparency logSecurity for ggcode 1.3.158
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for ggcode-1.3.158.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
