SANDCODE

Your private AI coding companion — a fully independent CLI agent. Bring your own model: z.ai, OpenAI, OpenRouter, Google Gemini, DeepSeek, Mistral, or any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM…).

$ sandcode
────────────────────────────────────────
  ※ SANDCODE — Your AI coding companion
  GLM-5.1 · 200k context · z.ai
────────────────────────────────────────
>

Status: v2.0.0 — major release that strips all first-party upstream coupling (telemetry, OAuth, vendor SDK, Bedrock/Vertex providers, upstream URLs). Env vars renamed ANTHROPIC_* → SANDCODE_* (no compat shim — see sandcode.sh/docs).

Install

From source (recommended for v2.0.0)

# Prereq: Bun >= 1.3
git clone https://github.com/Djsand/SANDCODE.git
cd SANDCODE
bun install
bun run build
bun dist/cli.js

The bun install step pulls the bundled @sandcode/browser-mcp workspace package via file:./src/vendor/sandcode-browser-mcp, so no extra setup needed.

Verify it works

$ bun dist/cli.js --version
2.0.0 (SANDCODE)

$ bun dist/cli.js --help
Usage: sandcode [options] [command] [prompt]
...

Symlink as sandcode

# Link the built binary
ln -s "$PWD/dist/cli.js" /usr/local/bin/sandcode
sandcode --version

First-run setup

Sandcode prompts you to pick a provider on first launch:

  [1] z.ai (GLM-5.1)              ← default
  [2] OpenAI (GPT-4o, o1, o3)
  [3] Google Gemini (2.5 Pro)
  [4] DeepSeek
  [5] Mistral
  [6] OpenRouter (200+ models)
  [7] LM Studio (local models)
  [8] Custom OpenAI-compatible endpoint

For most users, pick z.ai, OpenAI, OpenRouter, or LM Studio.

Note: the first-party (Sandcode-hosted) provider option was removed from the picker in v2.0.0 because its OAuth flow is a no-op stub. If you specifically need it, set provider: "firstParty" + SANDCODE_API_KEY + SANDCODE_BASE_URL directly in ~/.sandcode/config.json.

You can also set the provider non-interactively via env vars:

export SANDCODE_USE_OPENAI=1
export OPENAI_API_KEY=sk-...
sandcode "fix the failing test in src/auth/"

Per-provider env vars:

| Provider | Required env | |--------------|---------------------------------------| | z.ai | ZAI_API_KEY | | OpenAI | OPENAI_API_KEY + SANDCODE_USE_OPENAI=1 | | Gemini | GEMINI_API_KEY + SANDCODE_USE_GEMINI=1 | | DeepSeek | DEEPSEEK_API_KEY + SANDCODE_USE_DEEPSEEK=1 | | Mistral | MISTRAL_API_KEY + SANDCODE_USE_MISTRAL=1 | | OpenRouter | OPENROUTER_API_KEY + SANDCODE_USE_OPENROUTER=1 | | OpenAI-compat | OPENAI_COMPAT_API_KEY + OPENAI_COMPAT_BASE_URL + SANDCODE_USE_OPENAI_COMPAT=1 |

SANDCODE.md memory

Sandcode auto-loads instruction files at conversation start, in order:

1. ~/.sandcode/SANDCODE.md — user-scope (applies everywhere)
2. <cwd>/SANDCODE.md — project-scope (committed to repo)
3. <cwd>/SANDCODE.local.md — local-scope (per-checkout, gitignored)
4. <parent dir>/SANDCODE.md — walked up to your home directory
5. Any --add-dir <path> directories

Each loaded file is wrapped with a header showing its path so the model knows the source. Use these to give per-project conventions, style guides, or reminders the agent should always follow.

# Project-wide rules
echo "# Project conventions
- Run \`bun test\` after every change
- Use the existing \`logger.ts\`, don't import a new logging lib" > SANDCODE.md

Slash commands

| Command | Description | |---------------|------------------------------------------| | /help | Show available commands | | /init | Initialize SANDCODE in a project | | /model | Switch AI model | | /compact | Compact conversation context | | /clear | Reset conversation + caches | | /cost | Show token cost for the session | | /memory | View/edit loaded SANDCODE.md files | | /config | Open the settings UI | | /plugins | Manage plugins | | /rc | Start remote control server (Tailscale) | | /remember | Save memory for future sessions | | /commit | Smart commit workflow | | /verify | Run the verification agent on changes |

Run sandcode --help for the full CLI flag list.

Plugins

Sandcode is plugin-compatible (skills, hooks, MCP servers, agents, slash commands, output styles). Install from a marketplace:

/plugin marketplace add owner/repo
/plugin install plugin-name@marketplace

Desktop app (Windows + macOS)

SANDCODE also ships as a native Electron app — launch from the Start Menu or Applications folder. The desktop app embeds the same Ink TUI inside an xterm.js terminal driven by node-pty, so everything works the same as the CLI — same providers, same commands, same SANDCODE.md memory.

Build instructions are being updated as part of the desktop v1 scaffolding. See Task 2 of the implementation plan for the new structure and build process.

Browser extension (preview)

A Chrome extension at chrome-extension/ exposes the user's tabs, console, screenshots, and JS eval to the agent over MCP. The CLI side already advertises the 6-tool surface; the end-to-end CallTool relay between the in-process MCP server and the native messaging socket is not yet wired — install instructions and missing pieces are documented in chrome-extension/README.md.

To opt in: sandcode --sandcode-browser-mcp (no-op until the relay ships in a follow-up).

Configuration

~/.sandcode/
  settings.json          # User settings, plugins, permissions
  config.json            # API keys, model selection, provider
  keybindings.json       # Custom keybindings
  SANDCODE.md            # User-scope memory (always loaded)
  plugins/               # Installed plugins + marketplace cache
  projects/              # Per-project memory cache
  memory/                # Persistent cross-session memories

Settings merge order (last wins): defaults → ~/.sandcode/settings.json → .sandcode/settings.json → .sandcode/settings.local.json

Docs

Full documentation — migration guide, env vars, provider setup, removed-feature list, and config file layout — lives at sandcode.sh/docs.

Architecture

bin/sandcode.js               CLI entry (detects bun, spawns runtime)
src/entrypoints/cli.tsx       Fast-path routing (--version, --help, etc.)
src/main.tsx                  Commander + Ink React UI + REPL loop
src/tools/                    Built-in tools (Bash, Edit, Read, Glob, Grep…)
src/commands/                 Slash commands
src/utils/                    Config, auth, model, theme, hooks, plugins,
                              SANDCODE.md loader, attribution, etc.
src/services/                 API client, MCP, rate limits
src/components/               React/Ink terminal UI components
src/rc/                       Remote control server (Tailscale + WebSocket)
src/vendor/sandcode-browser-mcp/   Browser-extension MCP bridge stub
chrome-extension/             MV3 Chrome extension (preview)
shims/                        bun:bundle and MACRO shims
scripts/                      Postinstall (vendor copy + ripgrep download)

Known limitations (v2.0.0)

These features compile but are no-ops in this fork. They're stubbed so the build succeeds; users picking them get clean fall-through, not a crash.

• First-Party (1P) OAuth login. The OAuth flow against console.sandcode.sh is a no-op stub. The provider option was removed from the first-run picker in v2.0.0; if you need first-party access, set provider: "firstParty" + SANDCODE_API_KEY + SANDCODE_BASE_URL in ~/.sandcode/config.json directly.
• Browser-extension CallTool relay. The CLI advertises 6 browser tools but the relay between the in-process MCP server and the extension's native messaging port isn't wired yet. Tool list is visible to the agent; invocations no-op.
• Plugin install/update CLI. sandcode plugin install etc. accept args but don't perform installs. Use the in-app /plugins command for now.
• Voice mode. Disabled.
• Bridge / teleport / Grove / feedback surveys. Disabled — these were hosted features specific to the upstream deployment.

Development

bun install              # install deps
bun run build            # bundle to dist/cli.js
bun run typecheck        # TypeScript check
bun dist/cli.js          # run the built binary

# during development you can also do:
bun run dev              # run from source via tsx

License

Private software. All rights reserved.