gcode

gcode is a terminal AI coding agent written in Gerbil Scheme, with a native tool loop, MCP support, LSP tools, encrypted API key storage, a termbox TUI, verify-gated coding runs, and remote serve/connect modes.

The executable, Gerbil package namespace, project config, and runtime state directory all use the gcode name.

Status

• Builds a native .gerbil/bin/gcode executable through gerbil build.
• Uses gerbil-mcp for MCP tools and gerbil-lsp for LSP tools.
• Does not start jerboa-mcp or a Jerboa LSP server.
• Reads project config from ./gcode.json and global config from ~/.gcode/config.json.
• Stores sessions, encrypted keys, model caches, and other runtime state under ~/.gcode.

Quickstart

git clone https://git.cons.io/ober/gerbil-code
cd gerbil-code

make build
.gerbil/bin/gcode --version
.gerbil/bin/gcode config

For interactive use:

.gerbil/bin/gcode keys init
.gerbil/bin/gcode keys add anthropic
.gerbil/bin/gcode
.gerbil/bin/gcode --tui
.gerbil/bin/gcode -p "explain this repository"

For a local OpenAI-compatible endpoint such as MLX, start the endpoint and put the provider settings in gcode.json; see gcode.example.json.

Build Requirements

• Gerbil Scheme available as gerbil on PATH, or set GERBIL=/path/to/gerbil.
• A C compiler and standard build tools.
• gerbil-termbox, either at ../gerbil-repos/gerbil-termbox, ../gerbil-termbox, ~/mine/gerbil-repos/gerbil-termbox, or ~/mine/gerbil-termbox.
• OpenSSL development libraries. On macOS, build.ss also checks OPENSSL_LIB_DIR, pkg-config, and Homebrew openssl@3.

Build commands:

make build
make test
make install
make clean
GERBIL=/opt/gerbil/bin/gerbil make build

make install installs the native executable to ~/.local/bin/gcode by default. Override PREFIX or BINDIR for another user-writable location.

Running gcode without a command or prompt launches the full TUI. Use gcode --no-tui only when the minimal line-mode REPL is desired.

make test builds the native executable, runs the focused Gerbil unit/security regressions, exercises the isolated web-search worker and HTML parser, and runs the comprehensive 1,280-case Jerboa-parity behavioral suite. Use make test-providers separately for real provider round trips; it skips providers without configured credentials and is excluded from make test because it uses network access and API quota.

Documentation

Doc	Contents
Getting started	Prerequisites, build, first run, keys.
Configuration	gcode.json, provider settings, permissions, agents.
CLI reference	Main commands, flags, slash commands, verified runs.
MCP and LSP	Gerbil-only MCP/LSP behavior and expected commands.
TUI and themes	TUI launch, theme loading, checked-in theme configs.
Plugins	Runtime Gerbil .ss plugin loading and tool registration.
Development	Repo layout, build internals, verification workflow.

Layout

main.ss             executable entry point
build.ss            Gerbil build script and gcode exe target
core/               config, sessions, agent loop, guardrails, skills
provider/           LLM provider implementations and model registry
tool/               file, bash, git, web, image, patch, task, LSP, verified tools
mcp/                MCP stdio client
ui/                 CLI, TUI, serve, relay, connect
guardrails/         rescue, validation, step enforcement, response forcing
proxy/              OpenAI-compatible guardrail proxy
eval/               deterministic scenario/ablation harness
docs/               user and contributor docs

See AGENTS.md for repository instructions for coding agents and CLAUDE.md for Claude-specific reminders.