SGLCode

Coding Agent for Decentralised AI.

Singularity Layer's grid-native agentic coding CLI — tuned for small self-hosted models on the SGL Grid (a decentralized, confidential, OpenAI-compatible inference network), and BYOK-open for your own provider keys.

Unlike general coding agents that ship ~14k-token system prompts and pull their model catalog from a public registry, SGLCode is built around the grid's tight context windows: it discovers models (and their context_window) live from /v1/models, ships a sub-2k-token system prompt, budgets every request to the model's actual window, and auto-compacts older turns into a summary instead of dropping them — so a 16k or even 4k model never death-spirals.

Install

npm i -g sglcode     # or: bun add -g sglcode
sglcode              # cue the intro ✦

Runs on plain Node ≥ 20 — nothing else to install. (Bun is only needed if you want to hack on the source.)

Usage

export SGL_API_KEY=sk-...   # your Singularity compute key (never hardcode it)
sglcode                     # interactive REPL (intro, themes, mascot)
sglcode models              # list models the grid serves (with context windows)
sglcode run "<task>"        # run one task non-interactively
sglcode update              # self-update to the latest release
sglcode --resume            # pick up your most recent session
sglcode --no-intro          # skip the startup animation

REPL commands

| Command | What it does | |---------|--------------| | /model [id] | list grid models / switch model — also BYOK: /model openai/gpt-4o | | /permissions [mode] | ask (default) · accept-edits · yolo · plan (read-only) | | /compact | summarize older turns to free context | | /resume [n] | list / load recent sessions for this project | | /theme [name] | cream (default) · white · party · pink · green · blue · orange | | /mascot [name] | pick your creature (nova, void, wisp, singu, …) | | /plan /skills /reset /help /exit | the usual suspects |

Theme + mascot persist in ~/.sglcode/config.json; model choice and the bash allowlist persist per-project in .sglcode/settings.json.

Configuration (env)

| Var | Purpose | Default | |-----|---------|---------| | SGL_API_KEY | Bearer token for the grid (required for grid models) | — | | SGL_MODEL | Force a model ref (qwen-coder-7b, openai/gpt-4o, …) | auto-picked | | SGL_BASE_URL | Override grid base URL | https://grid.x402compute.cc/v1 | | OPENAI_API_KEY / OPENROUTER_API_KEY | Enable BYOK refs via /model | — | | TAVILY_API_KEY / BRAVE_API_KEY | Upgrade web_search backend | DuckDuckGo (no key) |

API keys are only read from the environment (or the wallet login, coming next). Never hardcoded, logged, or persisted in the repo.

Tools

read (with offset/limit), write, edit, bash, grep, glob, ls, web_fetch, web_search, undo_changes — file paths are sandboxed to the working directory; bash runs with a timeout; mutating tools pass a permissions gate (confirm-by-default, per-project allowlist, read-only plan mode) and their changes are shown as a green/red diff. Two harness tools are added only when usable: todo_write (planning) and skill (load a skill on demand).

Project context: drop an SGLCODE.md (or AGENTS.md) in your repo root and SGLCode injects it — size-capped so it can't blow a small window.

The small-model harness edge

Because grid models are small, the harness is what makes SGLCode good. See ../HARNESS_ARCHITECTURE.md for the full design:

• Planning — an externalized checklist (via todo_write) re-shown every turn, immune to history trimming; a weak model re-reads its plan instead of forgetting it mid-task.
• Skills — capability packages (SKILL.md + optional scripts) from <project>/.sglcode/skills/, ~/.sglcode/skills/, and the bundled skills/. Only a one-line catalog rides in the base prompt; full instructions load on demand. A conventional-commits skill ships in the box.
• Auto-compaction — when the window gets tight, older turns are summarized into a compact note by one cheap model call instead of being hard-dropped.
• Reliability — retries with backoff on grid hiccups, header timeouts, and a non-streaming fallback; malformed tool calls (JSON-in-text, almost-JSON args) are recovered; repeated identical failures stop the loop instead of death-spiralling.

Authoring a skill

.sglcode/skills/my-skill/SKILL.md

---
name: my-skill
description: One line the model uses to decide when to load this.
---
# Detailed instructions the model only sees after calling the skill tool.

How it works

/v1/models ──► model picker (context_window)
                     │
 user turn ──► budget engine (fit to window, compact/trim, size reply)
                     │
              stream /v1/chat/completions  ──► text + tool_calls
                     │                              │
              print deltas               permissions gate ──► execute tools
                     └──────────── loop until no more tool calls ─┘

Development

cd sglcode
bun install
bun run dev          # watch mode
bun run intro        # preview the startup screen (--theme=party --gallery)
bun run typecheck && bun test

Status

v0.1.x — live-grid verified core (streaming REPL, tool loop, budget engine, planning, skills, hardening) plus: startup identity (7 themes, mascots), web tools, auto-compaction, retry/fallback reliability, permissions, sessions + resume, BYOK providers, self-update. See ../V1_DESIGN.md and ../V1_PLAN.md. Coming next: wallet browser login billing Singularity credits, Ink TUI.

Lineage / license

SGLCode is an independent implementation in TypeScript/Bun. It was informed by studying sst/opencode (MIT) but contains no opencode code. It contains no code from the unlicensed tanbiralam/claude-code leak. See ../NOTICE.