# SANDCODE

Your private AI coding companion — a fully independent CLI agent powered by **z.ai GLM-5.1**.

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

## Install

```bash
# Prerequisites: Node.js >= 22 + tsx (or Bun >= 1.2)
npm install -g tsx

# Install SANDCODE
npm install -g Djsand/SANDCODE

# Run
sandcode
```

On first run you'll be prompted for your z.ai API key. That's it — no other setup needed. The postinstall automatically downloads ripgrep for your platform.

### Run from source

```bash
git clone https://github.com/Djsand/SANDCODE.git
cd SANDCODE
npm install
node bin/sandcode.js
```

---

## Features

- **Full codebase agent** — reads, writes, edits, searches files and runs commands with your approval
- **Ripgrep-powered search** — fast glob and grep across any size codebase
- **Plugin ecosystem** — compatible with Claude Code plugins: skills, hooks, MCP servers, LSP servers, slash commands
- **Remote control** — pair with your phone over Tailscale for mobile coding sessions (`/rc`)
- **Multi-provider support** — z.ai (default), OpenAI-compatible endpoints, AWS Bedrock, Google Vertex
- **Plugin marketplace** — install from official, community, or private marketplaces
- **Episodic memory** — semantic search across past conversations (via plugin)
- **Chrome DevTools** — inspect live web pages, debug UI, run Lighthouse audits (via plugin)

---

## Slash Commands

| Command | Description |
|---------|-------------|
| `/help` | Show available commands |
| `/init` | Initialize SANDCODE in a project |
| `/model` | Switch AI model |
| `/compact` | Compact conversation context |
| `/plugins` | Manage plugins |
| `/rc` | Start remote control server |
| `/remember` | Save memory for future sessions |
| `/review` | Code review current changes |
| `/commit` | Smart commit workflow |

---

## Plugin System

```bash
# Install from marketplace
/plugin install superpowers@superpowers-marketplace

# Add a community marketplace
/plugin marketplace add obra/superpowers-marketplace

# Create your own plugin
/plugin create my-plugin
```

Plugins can provide: skills, hooks, MCP servers, LSP servers, agents, output styles, and slash commands.

---

## Keybindings

| Key | Action |
|-----|--------|
| `Enter` | Send message |
| `Shift+Enter` | New line |
| `Escape` | Cancel / interrupt |
| `Ctrl+C` | Interrupt |
| `Tab` | Accept autocomplete |

Custom keybindings go in `~/.sandcode/keybindings.json`.

---

## Configuration

```
~/.sandcode/
  settings.json          # User settings, plugins, permissions
  config.json            # API key, model selection
  keybindings.json       # Custom keybindings
  plugins/               # Installed plugins + marketplace cache
  projects/              # Per-project memory
  memory/                # Persistent memories across sessions
```

Settings merge order: `defaults` → `~/.sandcode/settings.json` → `.sandcode/settings.json`

---

## Architecture

```
bin/sandcode.js          CLI entry (detects bun/tsx, 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
src/services/            API client, analytics, MCP, OAuth
src/components/          React/Ink terminal UI components
src/rc/                  Remote control server (Tailscale + WebSocket)
shims/                   bun:bundle and MACRO shims for tsx
scripts/                 Postinstall: vendor copy + ripgrep download
```

### Development

```bash
npm install              # Install deps + download ripgrep + copy vendors
npm run typecheck        # TypeScript check
npm run dev              # Run with Bun
npm link                 # Global `sandcode` symlink
```

### Production Build (requires Bun)

```bash
bun run build.ts
```

---

## License

Private software. All rights reserved.
