Skip to content
/
Tier B A19 Token-efficient encoding

gg (2-letter agent-native git client)

gg-cyclecore · cyclecore-dev/gg · ★ 0 · last commit 2026-01-24

Reduce AI agent token consumption by 96–98% on git/npm/brew operations by acting as a deterministic command broker that returns structured MCP payloads instead of full package schemas.

Best whenThe 2-letter binary name and sub-100-token outputs are first-class design requirements for agent-native tooling, not cosmetic choices.
Skip ifFull npm/brew schema dumps in agent context, Verbose CLI output when agents need structured data
vs seeds
spec-kit(cli-tool) but the problem domain is orthogonal — gg could be used alongside any seed framework.
Primitive shape 22 total
Commands 22
00

Summary

gg-cyclecore — gg (cyclecore-dev/gg)

gg is a 2-letter agent-native git client and package manager broker that acts as a "deterministic command broker" — converting complex repo/package operations into tiny MCP calls (11–62 tokens instead of 1,800–2,400). Its primary value proposition is 96–98% token savings on git/npm/brew tasks by returning structured MCP-ready payloads instead of full package schemas and metadata. It is model-agnostic (Anthropic, OpenAI, Ollama), installable via Homebrew/curl/npm/AUR, and ships a CLI2CLI (a2a) mode for pipeable agent-to-agent communication with sub-100-token outputs. A Pro tier (unlimited gg ask calls) is offered via CycleCore Technologies.

Compared to the seeds, gg is unlike any seed archetype — it is a tooling utility that reduces agent context consumption rather than a behavioral framework or workflow system. The closest analogy is a thin MCP wrapper (Archetype 3 element) but inverted: rather than exposing tools to agents, gg converts agent tool calls into minimally-sized structured responses.

01

Overview

Overview — gg (cyclecore-dev/gg)

Origin

gg is an open-source project by CycleCore Technologies (MIT license). It describes itself as:

"AI agents waste thousands of tokens every time they interact with git, npm, or brew because full schemas and metadata bloat the context. gg fixes that."

Philosophy

The core thesis is token efficiency through deterministic command brokering:

"It acts as a deterministic command broker: a thin, fast bridge that turns complex repo/package operations into tiny MCP calls (11–62 tokens instead of 1,800–2,400). Result: up to 96–98% token savings on git/npm/brew tasks — so agents stay fast, cheap, and focused on what matters."

Design Principles (from CLI2CLI a2a section)

  • <100 tokens per output — agents see minimal text
  • YAML frontmatter for structured parsing
  • Pipeable stdout (Unix philosophy)
  • --help for discovery

Benchmarks (from README)

Operation Without gg With gg Savings
Git operations ~1,800–2,400 tokens 11–62 tokens 96–98%
npm package lookup ~1,800 tokens ~18 tokens ~99%
Homebrew formula ~2,400 tokens ~22 tokens ~99%

Target Users

AI agents (Anthropic, OpenAI, Ollama) that need to interact with git, npm, or Homebrew. Also directly usable by humans with the same 2-letter commands.

02

Architecture

Architecture — gg (cyclecore-dev/gg)

Distribution

  • Type: CLI tool (standalone binary + npm package + Homebrew formula + AUR package)
  • Install (macOS/Linux):
    brew install cyclecore-dev/gg/gg
  • Install (any platform):
    curl -fsSL https://raw.githubusercontent.com/cyclecore-dev/gg/main/gg.sh | sh
  • Install (npm):
    npm install -g @ggdotdev/gg
  • Install (Arch Linux):
    yay -S gg-bin

Tech Stack

  • Primary language: Go (main.go, backend/ directory)
  • Shell script: gg.sh (universal installer)
  • npm package: npm/ directory

Directory Structure

gg/
├── main.go         # Main entry point
├── backend/        # Backend logic
├── gg.sh           # Universal installer
├── aur/            # Arch Linux AUR package
├── npm/            # npm package
└── Benchmark.md    # Token savings benchmarks

Multi-Provider Support

Provider API Key Format Models
Anthropic sk-ant-* claude-sonnet-4, claude-opus-4
OpenAI sk-* gpt-4o, gpt-4-turbo
Ollama (local) llama3, codellama, etc.

Required Runtime

  • Go runtime (or pre-built binary)
  • One of: Anthropic API key / OpenAI API key / Ollama (local)
  • gg init to configure on first run
03

Components

Components — gg (cyclecore-dev/gg)

CLI Commands

Core

Command Tokens Description
gg init - Configure provider and API key
gg maaza - Status and setup check
gg version - Show version
gg stats - Usage statistics

Package Manager

Command Tokens Description
gg npm <pkg> ~18 npm package → MCP
gg brew [-i] <formula> ~22 Homebrew formula (-i auto-installs)
gg chain <tools> variable Chain multiple MCPs
gg chain run <name> variable Execute saved chain
gg cool <toolbelt> ~90 Curated toolbelts (webdev/media/sec/data/devops)
gg cache status - Show cache size
gg cache clean - Prune old cache entries

Git Operations

Command Tokens Description
gg . ~12 Current repo → MCP
gg user/repo ~18 Any GitHub repo → MCP
gg pr <number> ~22 View/manage PR
gg run <cmd> ~15 Sandbox execution

AI Tools

Command Description
gg edit <file> AI-assisted file editing
gg ask "prompt" Generate code + PR (Pro: unlimited)
gg prompts Manage saved prompts
gg prompts add <name> Save a prompt
gg prompts run <name> Execute saved prompt

CLI2CLI (Agent-to-Agent a2a)

Command Tokens Description
gg a2a . ~5 Current repo → minimal endpoint
gg a2a ask "prompt" <100 Structured response, no git ops
gg a2a plan "task" <100 Numbered plan steps
gg a2a code "task" varies Raw code only, no prose

Pipe examples:

gg a2a . | gg a2a ask "summarize this repo"
gg a2a plan "auth system" | gg a2a code

Toolbelts (gg cool)

Belt Tools
webdev eslint, prettier, typescript, jest, playwright
media ffmpeg, imagemagick, exiftool
sec semgrep, snyk, trivy
data duckdb, jq, csvtojson
devops terraform, kubectl, docker
05

Prompts

Prompts — gg (cyclecore-dev/gg)

Note

gg is a CLI tool, not a prompt framework. It does not ship CLAUDE.md, AGENTS.md, skill files, or behavioral prompts. The "prompts" in gg are the structured MCP payloads it generates — minimal, schema-complete descriptions of packages and repos.

Excerpt 1: README Token Comparison Framing

Source: README.md Technique: Quantitative comparison to establish value proposition

## Why gg?

AI agents waste thousands of tokens every time they interact with git, npm, or brew 
because full schemas and metadata bloat the context. gg fixes that.

It acts as a **deterministic command broker**: a thin, fast bridge that turns complex 
repo/package operations into tiny MCP calls (11–62 tokens instead of 1,800–2,400).

Result: up to **96–98% token savings** on git/npm/brew tasks — so agents stay fast, 
cheap, and focused on what matters.

Excerpt 2: CLI2CLI Design Principles

Source: README.md Technique: Unix philosophy applied to agent-to-agent communication

**Design principles:**
- <100 tokens per output (agents see minimal text)
- YAML frontmatter for structured parsing
- Pipeable stdout (Unix philosophy)
- `--help` for discovery

**Pipe examples:**
# Agent chain: get repo → ask question
gg a2a . | gg a2a ask "summarize this repo"

# Plan then code
gg a2a plan "auth system" | gg a2a code
09

Uniqueness

Uniqueness — gg (cyclecore-dev/gg)

Differs From Seeds

gg is unlike any seed archetype in purpose. All 11 seeds are about how an agent reasons or what it produces; gg is about how cheaply an agent accesses external information. The closest structural analogy is the CLI-tool distribution type shared by spec-kit and claude-conductor, but the problem being solved is orthogonal. gg could be used alongside any seed framework — it reduces the token cost of the git/npm/brew operations those frameworks' agents perform during implementation, without replacing any behavioral or workflow primitive.

Positioning

gg is a token-efficiency infrastructure tool for AI agents, not a framework. It fills the gap between "agent wants to know what version of eslint to use" (currently: 1,800 tokens of npm schema) and "agent needs that answer" (gg: 18 tokens, structured). The 2-letter binary name is itself a design statement about agent-native UX.

Observable Failure Modes

  1. Zero stars (GitHub): Despite the compelling value proposition, public adoption at time of analysis is minimal
  2. Pro tier dependency: gg ask (the most complex AI operation) is rate-limited without Pro tier
  3. No behavioral layer: gg reduces token costs but provides no governance, workflow, or quality gates — it is purely a lookup/brokering tool
  4. Cache staleness: gg cache clean is manual; stale package metadata could cause agents to make decisions on outdated information
  5. Go-only implementation: Non-npm/non-Homebrew installations require Go runtime or pre-built binary
04

Workflow

Workflow — gg (cyclecore-dev/gg)

Primary Use Pattern

  1. gg init — configure provider and API key
  2. Use gg <operation> in place of direct git/npm/brew commands
  3. Output is MCP-structured, minimal token footprint
  4. Chain operations via pipe: gg a2a . | gg a2a ask "..."

Agent Integration Pattern

Agents call gg commands instead of raw shell commands for token-efficient operations:

# Instead of: git log --oneline -20 (full output, ~500 tokens)
gg .  # → structured MCP payload (~12 tokens)

# Instead of: npm info eslint (full schema, ~1800 tokens)
gg npm eslint  # → MCP payload (~18 tokens)

Phase-to-Artifact Map

Operation Artifact
gg npm <pkg> Structured MCP package descriptor (~18 tokens)
gg . Structured MCP repo descriptor (~12 tokens)
gg ask "prompt" Generated code + PR
gg a2a plan "task" Numbered plan steps in YAML frontmatter
gg chain <tools> Chained MCP results

Approval Gates

None — gg is a deterministic broker; no interactive approval gates.

Benchmarks

From Benchmark.md:

  • git/npm/brew operations: 96–98% token reduction
  • Full toolbelt (gg cool webdev): ~90 tokens for eslint+prettier+typescript+jest+playwright combo
06

Memory Context

Memory & Context — gg (cyclecore-dev/gg)

State Storage

gg maintains minimal persistent state:

  • Provider/API key config: Stored locally after gg init (location unspecified in README)
  • Cache: gg cache status / gg cache clean — cached MCP payloads for recently queried packages/repos
  • Saved prompts: gg prompts add <name> / gg prompts run <name> — named prompt storage
  • Saved chains: gg chain <tools> creates, gg chain run <name> executes — named tool chain storage
  • Usage stats: gg stats — usage statistics (content unspecified)

Cross-Session Persistence

Minimal — config, cache, prompts, and chains persist; no agent behavioral state or session context.

Memory Type

File-based local storage (specific paths not documented in README).

Context Window Impact

gg's entire value proposition is reducing context window consumption. A gg npm eslint call returns ~18 tokens vs ~1,800 for a direct npm API call — the saved tokens are available for actual reasoning tasks.

07

Orchestration

Orchestration — gg (cyclecore-dev/gg)

Multi-Agent Support

Partially — the CLI2CLI (a2a) mode enables agent-to-agent communication via piped stdout:

gg a2a . | gg a2a ask "summarize this repo"
gg a2a plan "auth system" | gg a2a code

Each gg a2a call is a minimal agent hop; the pipes compose them into simple chains.

Orchestration Pattern

Sequential (piped chain). No parallel fan-out, no hierarchical routing.

Isolation Mechanism

gg run <cmd> — sandbox execution mode.

Multi-Model Support

Yes — provider-agnostic:

  • Anthropic (claude-sonnet-4, claude-opus-4)
  • OpenAI (gpt-4o, gpt-4-turbo)
  • Ollama (local: llama3, codellama, etc.)

Execution Mode

One-shot (each gg command is a single operation).

Cross-Tool Portability

High — model-agnostic, works wherever the CLI runs.

08

Ui Cli Surface

UI & CLI Surface — gg (cyclecore-dev/gg)

Dedicated CLI Binary

Yes — gg is the entire product. 2-letter binary for minimal agent typing cost.

Installed via: Homebrew, curl, npm, AUR.

Command Surface

See 03-components.md for full command list. Key categories:

  • Core setup: gg init, gg maaza, gg stats
  • Package ops: gg npm, gg brew, gg cool, gg chain
  • Git ops: gg ., gg user/repo, gg pr, gg run
  • AI ops: gg edit, gg ask, gg prompts
  • A2A mode: gg a2a ., gg a2a ask, gg a2a plan, gg a2a code

Local Web Dashboard

None.

Observability

  • gg stats — usage statistics
  • gg cache status — cache status
  • gg maaza — health check and setup verification

Pro Tier

CycleCore Technologies Pro tier provides unlimited gg ask calls. No other functional differences documented.

Related frameworks

same archetype · same primary tool · same memory type

Context Mode ★ 16k
A19 Token-efficient encoding

Keeps raw tool output data out of the context window via sandbox execution and SQLite+FTS5 session indexing, reducing context…

lean-ctx ★ 2.2k
A19 Token-efficient encoding

A full-session context runtime that compresses file reads (10 modes), shell output (60+ patterns), and session memory (CCP) to…

Nemp Memory ★ 101
A19 Token-efficient encoding

Persists AI agent context across sessions as 100%-local plain JSON files with zero dependencies, zero cloud, and agent identity…

CogniLayer v4 ★ 28
A19 Token-efficient encoding

Provides AI coding agents with typed semantic memory, tree-sitter code intelligence, and a multi-agent coordination protocol to…

cursor-coding-agent-os (Mugiwara555343) ★ 3
A19 Token-efficient encoding

Lean/Verbose dual-mode Agent OS fork for solo developers on token budgets.

rtk (Real Token Killer) ★ 55k
A19 Token-efficient encoding

Intercepts Claude Code's Bash tool calls at the PreToolUse hook and compresses verbose CLI output (git status, test runners,…