spacialcode

Local AI coding CLI — a thin, opinionated harness that plans tasks, routes them to the best coding agent you already have installed (Claude Code, Codex CLI), and iterates until the work is done. No desktop app, no SaaS lock-in: it runs in any project folder and uses your existing accounts.

SpacialCode is the harness. The actual coding gets done by claude or codex — we just give them a shared workroom: planning, repo context, approval gates, project memory, and a clean summary at the end.

Install

curl -fsSL https://spacialmind.com/install/spacialcode.sh | bash

Or, with npm:

npm install -g spacialcode

Then verify:

spacialcode --version
spacialcode providers     # see which agents are detected on your PATH

Quick start

cd path/to/your/project
spacialcode                                    # interactive REPL
spacialcode run "fix the failing auth test"    # one-shot task
spacialcode run "refactor src/db.ts" --with codex

Add accounts so adapters can pick up the right credentials:

spacialcode accounts add claude-code work
spacialcode accounts add codex personal --key=sk-…
spacialcode accounts list

How it works

   you ──▶ spacialcode (the harness)
              │
              ├── repo scanner       (compact summary, language mix)
              ├── project memory     (.spacialcode/memory.md)
              ├── tool registry      (file / shell / git, all gated)
              ├── approval gate      (always | trusted | yolo)
              ├── director           (plan → run → review → iterate)
              └── adapter router ──▶ claude-code   (shells out to `claude`)
                                  ▶ codex          (shells out to `codex`)
                                  ▶ <your adapter> (drop in your own)

The Director is a deterministic planner in the MVP: it splits your task into a small ordered plan, routes each step to the highest-priority available adapter, and falls through to the next adapter if one fails. Approval gates sit outside the adapter so the human stays in the loop regardless of which agent is doing the work.

Configuration

User-wide config lives at ~/.spacialcode/config.json. Per-project overrides live at .spacialcode/config.json and the project's running memory lives at .spacialcode/memory.md — both are plain files you can edit by hand.

{
  "approvalMode": "trusted",
  "defaultProvider": "claude-code",
  "providers": [
    { "id": "claude-code", "enabled": true, "priority": 50 },
    { "id": "codex",       "enabled": true, "priority": 40 }
  ],
  "accounts": [
    { "provider": "claude-code", "label": "work" },
    { "provider": "codex",       "label": "personal", "apiKey": "sk-…" }
  ]
}

Approval modes:

REPL commands

Inside spacialcode:

/help                show help
/tools               list registered tools
/providers           availability of each configured adapter
/scan                fresh repo summary
/memory [note]       read or append project memory
/mode <m>            switch approval mode (always | trusted | yolo)
/with <provider>     route the next task to a specific adapter
/quit                exit

Writing a new adapter

Adapters are tiny. Implement Adapter from src/adapters/base.ts:

export class MyAdapter implements Adapter {
  readonly id = "my-agent";
  readonly label = "My Agent";
  async check(cfg) { /* return { available, bin?, reason? } */ }
  async run(input, cfg, account) { /* shell out, return AdapterRunResult */ }
}

Register it in buildRouter() in src/cli.ts. That's it — the planner, approval gate, and account/key plumbing are already in place.

Development

npm install
npm run build              # tsc → dist/
npm run typecheck
node bin/spacialcode.js providers

License

Apache-2.0