How It Works

Entry flow

bin/sandcode.js          # Detects runtime (Bun or tsx), sets up shims
  → src/entrypoints/cli.tsx  # Fast paths: --version, --help
    → src/main.tsx            # Commander setup, config loading, Ink root
      → src/screens/REPL.tsx  # Main conversation loop

1. bin/sandcode.js — the entry point. Detects whether Bun or tsx is available, sets up MACRO globals and bun:bundle shims, then spawns the TypeScript entry.
2. cli.tsx — handles fast-path CLI flags (--version, --help) without loading the full app. Everything else loads main.tsx.
3. main.tsx — sets up Commander, loads configuration, initializes auth, and renders the Ink React UI.
4. REPL.tsx — the main conversation screen. Manages message history, tool execution, and the interaction loop.

Runtime shims

SANDCODE uses shims to bridge the gap between Bun (production) and tsx (development):

• shims/loader.js — registers the module resolution hook for tsx
• shims/bun-bundle-hook.js — redirects bun:bundle imports to shims/bun_bundle.js
• shims/bun_bundle.js — feature() always returns false in dev mode
• shims/bun-preload.ts — defines globalThis.MACRO for Bun dev mode

Vendor packages

Dependencies that would normally come from npm are vendored into src/vendor/:

Package	Location	Purpose
@sandcode/sdk	src/vendor/sandcode-sdk/	Vendored SDK for API communication
color-diff-napi	src/vendor/color-diff-napi/	Stub — native module replacement
sandbox-runtime	src/vendor/sandbox-runtime/	Stub — sandbox environment

The postinstall script (scripts/copy-vendor.js) copies these into node_modules/ so they can be imported normally.

API client

The API client (src/services/api/client.ts) creates an SDK instance configured to communicate with the configured provider’s API endpoint (default: z.ai). Features like streaming, tool use, and function calling all work through the vendored SDK.

Tool system

SANDCODE’s tools are implemented in src/tools/:

• Bash — execute shell commands
• Edit — perform string replacements in files
• Read — read file contents
• Write — create or overwrite files
• Glob — find files by pattern
• Grep — search file contents

Each tool follows a standard interface with input validation, permission checks, and result formatting.

React Compiler output

Most .tsx files in src/components/ are React Compiler output with _c() memoization caches. See the React Compiler guide for editing guidelines.