# 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](https://sandcode.sh/docs)).

---

## Install

### From source (recommended for v2.0.0)

```bash
# 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

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

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

### Symlink as `sandcode`

```bash
# 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:

```bash
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.

```bash
# 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:

```bash
/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](https://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

```bash
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.
