ggcode
English | 中文
An AI coding agent for the terminal. Understands your codebase, edits files, runs commands, and ships code — with a polished TUI, resumable sessions, and multi-agent support.
Install
macOS / Linux:
curl -fsSL https://ggcode.dev/install.sh | bash
Windows:
irm https://ggcode.dev/install.ps1 | iex
Other methods: Homebrew · winget · npm · pip · build from source
All install scripts default to non-privileged (no sudo / admin required).
Quick Start
# 1. Run ggcode in your project
cd your-project
ggcode
# 2. On first launch, configure your API key (interactive prompt)
# Or set it directly:
# Or set up via the interactive wizard on first launch
# 3. Start coding — just type your request
New to ggcode? Read the Getting Started guide.
LAN Chat — Real-Time Team Collaboration
Every ggcode instance automatically discovers other instances on the same
local network via mDNS — no relay server, no accounts, no configuration.
| Feature | Description |
|---|
| Auto-discovery | mDNS finds peers automatically — zero config |
| DM & broadcast | Message individuals, teams, or everyone on the LAN |
| Agent-to-agent | Route messages to @agent for cross-instance delegation |
| Presence | See who's online, their project, role, team, and languages |
| File sharing | Drag-and-drop attachments up to 10 MB |
| Read receipts | Track message delivery and read status |
| Cross-platform | Works in TUI, Desktop GUI, and daemon mode |
| Privacy | Messages stay on your LAN — nothing goes through external servers |
Quick example — your agent can collaborate with peers:
You: "ask the platform team to review my PR"
Agent: lanchat(action='send_team', team='platform', message='Can you review PR #123?')
The built-in community key ensures interoperability regardless of
individual A2A auth configuration.
📖 Full LAN Chat Guide →
Features
- Codebase-aware — reads, understands, and edits your entire project
- Full dev toolkit — file edits, shell commands, Git, LSP, search, batch operations
- Semantic code search — BM25-based
code_search finds conceptually related code, not just keyword matches
- Code health analysis — cyclomatic complexity, function length, nesting depth metrics via
code_health
- Tech-debt scanner —
scan_todos surfaces TODO/FIXME/HACK markers with severity ranking and git-blame staleness
- Browser automation — Go-native CDP for SPA/JS testing without Node.js or Playwright
- Screenshot capture — full screen, window, or region screenshots for visual debugging
- Clipboard integration — read from and write to the system clipboard
- Editor launcher —
open_editor opens files in the user's IDE (VS Code, Cursor, JetBrains, Vim, etc.) at a specific line/column, auto-detected from env vars
- Agent-accessible undo —
undo_edit lets the LLM revert its own file edits via checkpoints, avoiding error-prone fix-forward when a previous change was wrong
- Batch file operations —
file_ops (delete, move/rename, mkdir with sandbox enforcement and file-tracker integration) and batch_replace (regex/literal find-and-replace across many files in one call) replace unsafe run_command("rm/mv") with first-class protected tools
- Schema-constrained tool validation — pre-execution pipeline that validates enum values, numeric bounds (min/max), string length constraints, and strips hallucinated parameters — saving wasted iterations on weak models
- Adaptive tool timeout — per-tool category-based timeout that adapts to observed latency, replacing a flat 5-minute default with sensible bounds (30–180s per category) so hung tools fail fast instead of wasting minutes
- Exit code intelligence — when commands fail with signals (137=OOM, 139=segfault, 134=abort, 130=SIGINT, 143=SIGTERM), the agent receives an actionable diagnostic hint instead of a bare exit code, enabling immediate root-cause diagnosis
- PTC (Programmatic Tool Calling) — the agent writes JavaScript in a sandboxed VM to batch-call read-only tools (read_file, grep, git_log, web_search, etc.) in a single round-trip, dramatically reducing context window consumption for multi-step analysis
- MCP integration — connect external tools and data sources, with dynamic tool refresh, server logging, full capability detection, and MCP sampling (servers can request LLM completions)
Platforms
Documentation
| Guide | Description |
|---|
| Getting Started | First steps, API key setup, basic usage |
| Installation | All install methods for every platform |
| CLI Reference | Commands, flags, pipe mode |
| Providers | LLM vendor and endpoint configuration |
| Slash Commands | In-TUI command reference |
| Permission Modes | Supervised and bypass (auto/autopilot accepted as legacy aliases) |
| MCP Servers | Connect external tools via MCP |
| gRPC Plugins | Build and install custom tool plugins (Go, Python, Node.js) |
| IM Integration | QQ, Telegram, Discord, Slack, Feishu, DingTalk |
| A2A Protocol | Cross-instance agent delegation |
| ACP / Editor |
Quick Links
License
MIT
