gold-agent

Zero-dependency infrastructure for AI-assisted coding:

• source-file skeleton compression
• autonomous build/test healing
• session auto-compaction
• repository map generation
• one-command local environment setup

gold-agent is designed for large codebases where agents waste tokens reading too much, lose time debugging small mistakes, and enter projects without architectural context.

Vision

Modern coding agents are strong, but they still fail in predictable ways:

• they read full files when a structural view would be enough
• they get trapped in small validation-fix loops
• they carry too much stale context across long sessions
• they start refactors without a compressed map of the repo

gold-agent solves those problems with a deterministic, local-first toolkit built with zero external runtime dependencies.

Core Features

1. Skeleton Compression

compressor.ts strips implementation bodies and keeps imports, declarations, signatures, and structure. This gives agents a high-signal view of large files before they do targeted reads.

2. Self-Healing Validation

healer.ts runs a failing command, captures the first source-file error, asks a fast LLM for a strict JSON patch, applies it behind a backup, reruns validation, and rolls back automatically if the retry still fails.

3. Auto-Compact

auto-compact.ts monitors session token usage and summarizes older context when the conversation approaches the context limit.

4. Repo Map Generation

repo-mapper.ts recursively scans a repository, respects .gitignore, extracts structural signatures with regex, and writes a compressed REPO_MAP.md.

5. Shell and Agent Wiring

setup.sh wraps common shell workflows, and gold-agent install wires the tool into:

• your shell rc file
• ~/.codex/AGENTS.md
• ~/.claude/settings.json

Why Zero Dependency

The project is intentionally built without external runtime packages:

• no CLI framework
• no AST libraries
• no patching libraries
• no config-management libraries

That keeps installation simple, behavior transparent, and failure modes easy to reason about.

Architecture Boundary

gold-agent is intentionally built around standalone local tools and shell hooks.

There is no background listener requirement. The project ships only direct local tooling:

• compressor.ts
• healer.ts
• auto-compact.ts
• repo-mapper.ts
• cli.ts
• setup.sh

Installation

Prerequisites

• Bun
• an OpenAI or Anthropic API key if you want to use autonomous healing or LLM-backed compaction

Global CLI Setup

Clone the repository, then install and wire everything with:

npm install -g .
gold-agent install

This does three things automatically:

1. Appends source /path/to/setup.sh to your ~/.zshrc or ~/.bashrc
2. Injects a managed gold-agent rules block into ~/.codex/AGENTS.md
3. Creates and registers a Claude Stop hook in ~/.claude/settings.json

Then reload your shell:

exec zsh

If you use Bash:

exec bash -l

Quick Install (macOS/Linux)

If Bun is already installed, you can install directly from GitHub:

curl -fsSL https://raw.githubusercontent.com/cjaryou/gold-agent/main/install.sh | sh

This installs the project under ~/.local/share/gold-agent and creates:

~/.local/bin/gold-agent

Add it to PATH if needed:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
exec zsh

Homebrew

The repository now includes a Homebrew formula template at:

Formula/gold-agent.rb

Recommended release flow:

1. Tag a release such as v0.1.0
2. Compute the release tarball SHA256
3. Run scripts/update-homebrew-formula.sh <version> <sha256>
4. Publish that formula in a tap repository such as cjaryou/homebrew-gold-agent

After the tap exists, the install shape is:

brew install cjaryou/gold-agent/gold-agent

CLI Usage

Generate or refresh the repo map

gold-agent map

This writes REPO_MAP.md to the current project root.

Heal a failing validation command

gold-agent heal bunx tsc --noEmit
gold-agent heal npm test

Compact the latest session

gold-agent compact --check --latest
gold-agent compact --latest

What gold-agent install Actually Changes

The installer is intentionally idempotent and conservative.

Shell rc file

It detects zsh or bash and appends the setup.sh source line only if the project path is not already present.

Codex rules

It writes a managed block into ~/.codex/AGENTS.md using start/end markers, so rerunning install replaces the same block instead of duplicating it.

Claude Stop hook

It creates:

~/.claude/hooks/gold-agent-stop.sh

Then it patches:

~/.claude/settings.json

If settings.json already exists, the installer creates a backup first:

~/.claude/settings.json.bak

If the existing JSON is invalid, installation aborts rather than guessing how to rewrite the file.

Shell Wrapper Behavior

After installation, setup.sh provides:

• compressed cat for source files
• transparent healing wrappers for common validation commands

Examples:

• tsc --noEmit
• bunx tsc --noEmit
• npm test
• npm run build
• bun test
• bun run build

These commands are routed through the deterministic Try-Heal-Retry workflow when healing is enabled.

Typical Workflow

1. Enter a repository
2. Run gold-agent map
3. Let the agent read REPO_MAP.md before deep code inspection
4. Work normally in the shell with wrapped validation commands
5. If a validation command fails, use gold-agent heal ...
6. Let the Claude Stop hook trigger compaction on long sessions

File Overview

• cli.ts: global CLI entrypoint and installer
• compressor.ts: file skeletonizer
• healer.ts: deterministic self-healing loop
• auto-compact.ts: session compactor
• repo-mapper.ts: repository structure map generator
• setup.sh: shell wrapper layer
• AGENTS.md: project-level agent rules

Development

Run the CLI locally without global install:

bun run cli.ts --help
bun run cli.ts map
bun run cli.ts heal bunx tsc --noEmit
bun run cli.ts compact --check --latest

Typecheck a single file in isolation:

bunx tsc --noEmit --ignoreConfig --strict --target ESNext --module ESNext --moduleResolution bundler --types bun-types cli.ts

Safety Model

The project prefers reversible behavior:

• healer.ts uses backup-write-retry-rollback
• repo-mapper.ts is read-only except for REPO_MAP.md
• auto-compact.ts only writes transcripts when thresholds are crossed
• cli.ts install avoids duplicate config writes and backs up Claude settings

License

MIT