ggcode

# ggcode

<p align="center">
  <img src="ggcode_cli_banner_1775456774280.png" alt="ggcode" width="600" />
</p>

**English** | **[中文](README_zh-CN.md)**

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:**
```bash
curl -fsSL https://ggcode.dev/install.sh | bash
```

**Windows:**
```powershell
irm https://ggcode.dev/install.ps1 | iex
```

**Other methods:** [Homebrew](docs/guide/install.md#macos) · [winget](docs/guide/install.md#windows) · [npm](docs/guide/install.md#npm) · [pip](docs/guide/install.md#pip) · [build from source](docs/guide/install.md#build-from-source)

> All install scripts default to non-privileged (no sudo / admin required).

## Quick Start

```bash
# 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](docs/guide/getting-started.md)**.

---

## LAN Chat — Real-Time Team Collaboration

<p align="center">
  <strong>Zero-config P2P messaging between ggcode instances on your LAN</strong>
</p>

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 →](docs/guide/lan-chat.md)**

---

## 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)
- **gRPC plugins*

... (truncated)