Skip to content

getting-started.md

Latest commit

 

History

History
94 lines (68 loc) · 2.81 KB

getting-started.md

File metadata and controls

94 lines (68 loc) · 2.81 KB
Raw

Getting Started

1. Install ggcode

See the Installation Guide for all available methods.

2. Configure Your API Key

On first run, ggcode auto-detects your environment and prompts for configuration:

ggcode

The onboarding wizard will:

  • Ask you to select a provider (Z.ai, OpenAI, Anthropic, etc.)
  • Prompt for your API key
  • Write the configuration to ~/.ggcode/ggcode.yaml
  • Store the API key securely in ~/.ggcode/keys.env

You can also manually create the config file. See Configuration for details.

Manual Setup

Create ~/.ggcode/ggcode.yaml:

vendor: openai
endpoint: default
model: gpt-4o

Then add your API key to ~/.ggcode/keys.env:

OPENAI_API_KEY=sk-your-key-here

Or set it via environment variable:

export OPENAI_API_KEY=sk-your-key-here

3. Start Chatting

ggcode

Type a message and press Enter. ggcode will:

  1. Send your message to the configured LLM
  2. Stream the response in real-time
  3. Execute any tool calls (file reads, searches, etc.) with your approval

Input Modes

The input supports three modes:

  • Normal (❯): Chat with the agent (default).
  • Shell ($): Type $ or ! to run shell commands inline. Exits after each command.
  • Chat (#): Type # to send LAN Chat messages to other ggcode instances. Stays active until Esc.

4. Essential Slash Commands

Command Description
/help Show available commands
/sessions List and resume sessions
/model [name] Switch model
/mode [mode] Switch permission mode (supervised/bypass; auto/autopilot accepted as legacy aliases)
/compact Compact conversation to save context
/exit Exit ggcode

The agent itself can also reclaim context by calling the compact_context tool (Context-as-Tool): it runs a cheap mechanical pass immediately and, at or above the auto-compact threshold, schedules background summarization that applies at the next turn boundary.

Compaction is lossy, so anything it removes (summarized-away turns and superseded tool results) is kept in a session-scoped archive (~1MB, oldest entries evicted first). The agent can retrieve the verbatim original text later via the read-only recall_compacted tool — e.g. to recover an exact error message or command output that predates the last summary — instead of re-running the work.

5. Next Steps