-8b5cf6?style=flat-square){kind=icon}
Humans and agents work in the same near-real-time 3D view of a codebase, and you steer it by voice.
Maintainer: John O'Hare
Architecture · Crates · Quick start · Ecosystem · Status · Docs
Codescape extracts a code graph from one or more repositories, lays it out in
3D on the GPU (or the CPU), and streams it to a desktop browser client and a
Godot XR headset client from one port. Agents and people appear in the graph
at the node they are touching, as they touch it. You talk to the scene with
push-to-talk: "focus on the parser", "who calls parse_config", "what is
claude doing". Every spoken or typed request becomes a typed command before
anything runs.
Codescape is a code-work tool. It is deliberately separate from the knowledge-work system it was born beside (VisionClaw): it reads source trees, never a knowledge corpus, and that separation is a tested property (see Security posture).
The VisionClaw and agentbox source trees at the symbol tier (L2): 29,819 nodes, 77,925 edges, CUDA layout on an RTX A6000. The Rust backend is the large mass on the left and the TypeScript client the smaller one on the right.
The screenshots below were captured for the 19 October 2026 README update from the desktop client at 1920×1080 through browser automation, against the Codescape service running on the CUDA engine. The scene is the real VisionClaw and agentbox checkouts, not a demo dataset.
A local 21 October development commit adds a collapsible repository panel, estate-scene links and revised SpaceMouse axes. That commit (ffb98c2) was not on the published main branch when this documentation update was prepared. These controls remain pending publication; the screenshots below predate them. See deployment configuration for the published scene and input contract.
Captured gallery: tiers, filters, queries and timeline
The client shows one tier at a time: leave it on auto or pin L0, L1 or L2 from the tier panel. L0 shows directories, L1 files, L2 symbols.
| L0, directories | L1, files |
|---|---|
 |
 |
Language buttons, hide tests and the community chips work on the live scene. Below, Rust only with tests hidden removes the TypeScript client entirely, and community 72 isolates to one cluster of WebSocket and frame-dispatch code.
| Rust only, tests hidden | Community 72 isolated |
|---|---|
 |
 |
The command box takes the same grammar as push-to-talk (Voice and typed commands). Names are resolved fuzzily and the ranked candidates are shown, so a near miss is visible rather than silently wrong.
focus on whelk |
callers of apply_delta |
|---|---|
 |
 |
what is affected by whelk_blocker highlights the 22 nodes within three hops. The inspector (top right) shows the symbol, its file and line span and its community, and rewind 5 minutes drives the timeline bar and summarises the window.
Not shown: agent presence (an actor appearing at the node it touches), voice and the XR client. Those need the hook token, the speech services and a headset respectively, and are described in Status & honesty.
Codescape is one section of the VisionFlow mesh. It is a code-work tool: it reads source trees and never a knowledge corpus. It was born inside VisionClaw and is now its own repository (ADR-0001).
| Sibling | Relationship |
|---|---|
| VisionFlow | The canon: ecosystem map, compatibility matrix and honest status ledger. |
| VisionClaw | The host deployment. It mounts this repository as the codescape/ submodule, owns the compose service and nginx route, builds the CUDA PTX, and publishes visionclaw-wire, the frozen position wire. Its Godot XR client connects through /wss. |
| agentbox | The agent container. The activity-sink hook (ADR-2146; merged, default-off) posts agent activity to :4101. |
| loom | Optional out-of-grammar command parse (CODESCAPE_LOOM_URL); voice runs without it. |
| graphicle | The code-graph extraction engine, used unmodified as a pinned git dependency. |
Standalone use needs none of these: the CPU layout engine, the desktop client and the two permissive crates build and run on their own (see Quick start).
flowchart LR
subgraph sources[Repositories, read-only]
R1[repo A]
R2[repo B]
end
subgraph ingest[codescape-ingest]
G[graphicle extract<br/>+ incremental patch]
A[Leiden communities<br/>centrality, LOD tiers]
end
M[codescape-model<br/>types, interned ids,<br/>V3 record mapping]
L[codescape-layout<br/>CPU Barnes-Hut oracle<br/>CUDA engine, runtime PTX]
C[codescape-collab<br/>actors, heat, floor,<br/>command grammar]
subgraph server[codescape-server]
S4100[:4100 clients<br/>REST, /ws/positions,<br/>/ws/events, /ws/voice,<br/>/wss, /ws/presence]
S4101[:4101 hook ingest<br/>bearer token]
end
D[Desktop client<br/>React, three, R3F]
X[Godot XR client<br/>unchanged, via /wss]
H[Agent activity hook<br/>agentbox ADR-2146]
subgraph voice[Voice stack]
ASR[nemotron-asr]
TTS[pocket-tts]
LOOM[Loom door<br/>out-of-grammar parse]
end
R1 --> G
R2 --> G
G --> A --> M
M --> L --> S4100
M --> C --> S4100
H -- POST /ingest/v1/activity --> S4101 --> C
S4100 <--> D
S4100 <--> X
S4100 <--> ASR
S4100 --> TTS
S4100 -. fallback only .-> LOOM
Positions go out as the frozen 52-byte V3 record inside V5 envelopes, the
same position record VisionClaw’s clients decode. The shared record reduces decoder changes; client connection, presence and device acceptance remain separate integration work. Topology, selections, captions and query results go out as JSON on
/ws/events. There is no Codescape-specific wire format.
| Crate | Role | Licence | Publishable |
|---|---|---|---|
codescape-model |
Pure types: nodes, edges, interned 26-bit wire ids, snapshots, deltas, LOD tiers, community matching, V3 record mapping. No I/O. | MIT OR Apache-2.0 | yes |
codescape-collab |
Pure collaboration state: actor registry, activity heat, path resolution, the single push-to-talk floor, the command grammar and LLM-fallback schema. No I/O. | MIT OR Apache-2.0 | yes |
codescape-ingest |
The graphicle facade: extraction, incremental cache, live patching, communities, centrality, affected/path/search queries. The only crate that uses graphicle. | AGPL-3.0-only | no |
codescape-layout |
CPU Barnes-Hut layout (the conformance oracle) and, behind cuda, a thin cust driver over runtime-loaded PTX with ABI and provenance checks. |
AGPL-3.0-only | no |
codescape-server |
actix-web: every network adapter, the static desktop bundle, voice adapters, /wss emulation for XR. |
AGPL-3.0-only | no |
client/ |
Desktop browser client (Vite, React, three, React Three Fiber). | AGPL-3.0-only | no |
A permissive crate never depends on an AGPL crate. See LICENSE.
From this repository root, build the browser client first (Node 22.3 or later and Rust 1.94 or later):
cd client
npm ci --include=dev
npm run build
cd ..
cargo run --release -p codescape-server -- \
--bind 127.0.0.1 \
--data-dir ./.codescape \
--static-dir target/codescape-dist \
--repo myrepo=/path/to/myrepoOpen http://127.0.0.1:4100/, select a tier, then try overview and focus on <symbol-name> in the command box. The path in --repo must name the source tree you want to inspect. Voice additionally needs speech services; typed navigation does not.
--repo is repeatable (--repo a=/src/a --repo b=/src/b). The default data
directory is /data/codescape, which is rarely writable on a workstation;
./.codescape is gitignored. The CPU engine needs no GPU and no CUDA
toolkit.
cargo run --release -p codescape-server --features cuda -- \
--bind 127.0.0.1 --data-dir ./.codescape --repo myrepo=/path/to/myrepo
# with CODESCAPE_PTX_DIR pointing at a directory holding the unified PTX
# and its ptx-build-manifest.txtThe engine refuses PTX whose ABI or build provenance does not match, and falls
back to the CPU engine with the reason shown in /api/health.
VisionClaw mounts this repository as a git submodule at codescape/ and owns
the compose service and the nginx location (see deploy/README.md).
Run from the VisionClaw checkout, in its authorised host shell:
git submodule update --init codescape
CODESCAPE=1 ./scripts/launch.sh up dev
# then browse http://<host>:3001/codescape/Push-to-talk holds a single floor. Speech goes to nemotron-asr; the transcript is parsed by a deterministic grammar; only an utterance the grammar cannot parse goes to the Loom door, whose output must pass the command schema or it is spoken back and never executed. Typed commands use the same grammar.
| Say | Does |
|---|---|
focus on X, focus |
fly to and select X (or the current pick) |
explain X, what is X |
retrieve and summarise X |
callers of X, who calls X |
callers, up to 10 hops |
callees of X, what is called by X |
callees, up to 10 hops |
what is affected by X, affected by X, what does X affect |
blast radius |
path from X to Y, path between X and Y |
shortest dependency path |
show only rust, show only community 3, show all, hide tests |
filters |
zoom in, zoom out, overview, back |
camera |
rewind 5 minutes, replay, live |
timeline (rewind up to 7 days) |
what is claude doing, what is happening, who is here |
presence report |
follow claude, stop following |
camera follows an actor |
ask claude to <task> |
delegate to an agent: parsed today, dispatched only from P6 through a browser-signed intent |
The goldens in crates/codescape-collab/tests/grammar_golden.rs are the
authoritative phrase list.
Configuration reference
Every flag has a CODESCAPE_* environment variable. The main ones:
| Variable | Default | Purpose |
|---|---|---|
CODESCAPE_PORT |
4100 |
Client HTTP and WebSocket port |
CODESCAPE_INGEST_PORT |
4101 |
Hook-ingest port; never publish it |
CODESCAPE_BIND |
0.0.0.0 |
Bind address for both listeners; use 127.0.0.1 outside a container |
CODESCAPE_REPO |
required | label=path, comma separated |
CODESCAPE_EXCLUDES |
none | Extra glob excludes on top of .gitignore, comma separated |
CODESCAPE_DATA_DIR |
/data/codescape |
Interner, graphicle cache, positions, timeline |
CODESCAPE_STATIC_DIR |
none | Built desktop client served at / |
CODESCAPE_INGEST_TOKEN_FILE |
none | Bearer token for :4101; unset disables the ingest listener |
CODESCAPE_PATH_MAP |
none | FROM=TO[:FROM=TO...], rewrites the paths agents report to the paths Codescape reads |
CODESCAPE_PREFER_CUDA |
true |
Use the CUDA engine when compiled in and usable |
CODESCAPE_CUDA_DEVICE |
best free | Device ordinal (read by codescape-layout); set CUDA_DEVICE_ORDER=PCI_BUS_ID |
CODESCAPE_PTX_DIR |
none | Directory holding visionclaw_unified.ptx and ptx-build-manifest.txt; checked for ABI and provenance at load (ADR-0001) |
CODESCAPE_TRUST_PROXY |
false |
Honour X-Forwarded-* from a reverse proxy |
CODESCAPE_TRUST_PROXY_FROM |
any peer | Peers (IPs, CIDRs, hostnames) whose forwarded headers are trusted; requires TRUST_PROXY |
CODESCAPE_PUBLIC_PATH_PREFIX |
empty | Prefix the proxy strips, such as /codescape |
CODESCAPE_ALLOWED_ORIGINS |
same origin + loopback | Extra browser origins allowed to open WebSockets |
CODESCAPE_ASR_URL |
ws://nemotron-asr:8000/api/asr-streaming |
Streaming speech recognition |
CODESCAPE_TTS_URL |
http://pocket-tts:8000 |
Speech synthesis |
CODESCAPE_LOOM_URL |
none | OpenAI-compatible .../v1 base for the out-of-grammar fallback; unset disables it |
CODESCAPE_SHARE_AGENT_TEXT |
false |
Show agents' prompt and answer text to every viewer (default: tool names only) |
codescape-server --help lists the rest (FRAME_HZ, LOOM_MODEL,
TTS_VOICE, PUBLIC_ORIGIN, REEXTRACT, INCLUDE_DOCS, LOG_LEVEL and the
P6 auth flags).
- Authentication is open until P6.
/api/healthreports"auth":"open". NIP-98 and the allowlist remain planned.--require-authcurrently refuses startup; it does not enable a verifier (source). Until then, do not expose:4100to a network you do not trust. Under VisionClaw the port is published on host loopback only; the dev nginx path/codescape/on:3001is a recorded dev-only owner waiver. - Hook ingest on
:4101takes a constant-time-compared bearer token and is never published outside the container network. - Isolation from knowledge-work systems is enforced in layers
(docs/BASELINE-codescape.md):
- the resolved build graph contains no ontology, memory, vault, Oxigraph,
Postgres, RuVector, Solid or VisionClaw-server crate, no
visionclaw-*crate butvisionclaw-wire, nothing from the VisionClaw repository, and no AGPL crate under a permissive one (tests); - the server exits 2 at boot if
RUVECTOR_PG_CONNINFOis set (test); - the client imports nothing outside its own tree and an allowlist of packages (test);
- its container mounts source directories read-only and never a corpus (deployment contract);
- outbound connections go through one allowlist: ASR, TTS, the Loom door and, from P6, the voice-intent endpoint (code; an egress test is open).
- the resolved build graph contains no ontology, memory, vault, Oxigraph,
Postgres, RuVector, Solid or VisionClaw-server crate, no
- No signing keys. Agent dispatch, when it lands, is a kind-31402 event signed in the browser and relayed, never signed by the server.
cargo test --workspace --locked # CPU only; incl. the isolation suite
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --features codescape-server/cuda # needs a CUDA toolkit to link, no device
cd client && npm ci && npm run typecheck && npm test && npm run buildAGENTS.md has the full list. CI (.github/workflows/ci.yml) runs all of it.
Publication checked 21 October 2026 against main e300451. Local development at ffb98c2 adds the repository panel, scene links and SpaceMouse mapping; this documentation publication leaves that feature commit unmerged. The phase evidence below records earlier runs; its counts and hardware observations are not fresh results for this revision.
The recorded 18 October host setup serves /codescape/ through VisionClaw’s development nginx on port 3001 (ADR-2143 A4). The evidence index links the earlier headset run. This README review has not revalidated the running host, current GPU conformance or headset behaviour.
Earlier reported 100k-node figures (7.8 ms GPU step and 13.7 s cold settle) miss the 5 ms / 10 s targets. The evidence index says performance and conformance numbers were reported without a committed rerun; treat them as provisional, not certified measurements. Evidence: docs/evidence/README.md.
Things to know before relying on it:
- The CUDA layout engine drives VisionClaw's
visionclaw_unifiedPTX (a 53-fieldSimParamsmirror and thethrust_sort_key_valuecontract). Without that PTX, the CPU Barnes-Hut engine runs. - The deploy contract (deploy/README.md) is VisionClaw-shaped. Another host writes its own compose and proxy configuration.
- This is v0.1.0 with a short history: the repository was imported with fresh history (Provenance).
Codescape was designed and built inside VisionClaw under ADR-2143 ("Codescape
is a separate section with its own Cargo workspace, its own port and a tested
isolation boundary") and its amendments A1 to A4, on the feat/codescape
branch from commit b63068e3d. It was imported into this repository with a
fresh history from VisionClaw cac36a028 on main (source range
b63068e3d^..cac36a028); ADR-0001
records why and how, and docs/evidence/import-gate.txt
holds the import gate output.
The code-graph engine is graphicle,
a Rust port of Graphify, licensed Apache-2.0 and used unmodified as a pinned git
dependency (rev 003f93605d895ed69f0cf06690dd296474385b99).
Index: docs/README.md · governing document: BASELINE-codescape.md · decisions: docs/adr · evidence: docs/evidence · deployment contract: deploy/README.md · desktop client: client/README.md · agent instructions: AGENTS.md.
Per directory; see LICENSE. codescape-model and codescape-collab
are MIT OR Apache-2.0; everything else is AGPL-3.0-only.
Corpus and data terms do not apply: Codescape reads source trees only.
Part of VisionFlow: Codescape shows the code; VisionClaw hosts it and reasons over the knowledge corpus; agentbox runs the agents whose activity appears in the scene; loom grounds the model behind the door; solid-pod-rs stores sovereignly; the forum and website provide governance and operator surfaces.