Static project documentation

Workbench CLI

This site documents how the reconstructed Workbench CLI works, what the cloud and remote-control surfaces do, what state the repo is in right now, and the 20 highest-value improvements that would move it closer to a maintainable release.

Audit date: 2026-03-31 Source files in src/: 1,929 Extracted files in stubs/: 493

Install

bun install succeeds.

Build

bun run build succeeds and emits dist/cli.js.

Typecheck

bun run typecheck reports 4,469 TypeScript errors in this checkout.

Cloud Logic

Remote control, teleport, direct connect, and managed settings are all materially implemented.

Overview

This repository is a reconstructed agentic CLI codebase built around Bun, React, a custom Ink fork, a large tool system, MCP integration, and several cloud-facing session flows. The central runtime is real and substantial: there is enough code here to study architecture, trace the execution path, and understand how local, remote, and teleported sessions are meant to behave.

The repo is not in release shape. The biggest gaps are missing generated or extracted source files, partial native/private shims, and heavy type drift between the recovered source and the dependency versions currently installed.

Architecture completeness

High. Most of the core execution, UI, tools, and cloud flows are present.

Build integrity

Medium. A fresh install now produces a working bundle, but the fallback shim layer is still fragile.

Type integrity

Low. The checkout currently fails typecheck at scale.

Cloud feature depth

Medium. Remote-control and teleport logic are real, but the release surface is incomplete.

How it works

  1. Build stage. build.ts bundles src/entrypoints/cli.tsx, injects a small MACRO set, and relies on shims/bun-bundle.ts to disable all feature flags by returning false.
  2. CLI bootstrap. src/entrypoints/cli.tsx handles fast paths such as version printing and special entrypoints, then hands control to src/main.tsx.
  3. Initialization. src/entrypoints/init.ts turns on config loading, safe environment variables, TLS and proxy setup, telemetry bootstrapping, scratchpad setup, and cleanup hooks.
  4. Context collection. src/context.ts prepares system and user context, including git state snapshots and CLAUDE.md memory injection.
  5. Conversation engine. src/QueryEngine.ts owns turn lifecycle, message state, usage, and SDK-facing session behavior. src/query.ts runs the actual streaming loop.
  6. Model and tool orchestration. src/services/api/claude.ts streams model responses, while src/services/tools/StreamingToolExecutor.ts and src/services/tools/toolOrchestration.ts execute tool calls with permission checks and concurrency rules.
  7. Terminal UI. src/replLauncher.tsx mounts src/screens/REPL.tsx, which is the main full screen interface built on top of the custom Ink implementation in src/ink/.
  8. Extensibility. Slash commands come from src/commands.ts, tools from src/tools.ts, MCP servers from src/services/mcp/, plugins from src/utils/plugins/, and skills from src/skills/.
  9. Cloud and remote execution. Remote-control, teleport, direct connect, and session transport are split across src/bridge/, src/remote/, src/server/, and src/utils/teleport.tsx.

Main files at a glance

File Role Why it matters
build.ts Bundle entry and macro injection Defines what ships and what feature-gated code survives.
src/entrypoints/cli.tsx Fast-path bootstrap Decides whether the process becomes the CLI, a bridge, or a special worker.
src/main.tsx Main runtime coordinator Registers commands, parses options, handles resume, teleport, and remote sessions.
src/entrypoints/init.ts Config, auth, network, telemetry init Most cross-cutting startup side effects live here.
src/context.ts Prompt context builder Injects git and memory context into every session.
src/QueryEngine.ts Per-session execution engine Holds state across turns for SDK and future non-REPL usage.
src/query.ts Streaming query loop Runs model sampling, tool execution, retries, and compaction behavior.
src/services/api/claude.ts Model request layer Converts tools, context, betas, and auth into model calls.
src/services/api/client.ts Provider client factory Creates Anthropic, Bedrock, Foundry, or Vertex clients.
src/services/tools/StreamingToolExecutor.ts Streaming tool runner Controls tool concurrency, cancellation, and result ordering.
src/screens/REPL.tsx Main interactive UI Largest single UI file and the center of operator experience.
src/services/mcp/client.ts MCP transport and tool binding Connects external MCP servers into the tool layer.
src/utils/plugins/pluginLoader.ts Plugin discovery and loading Owns marketplace, cache, versioning, and local plugin resolution.
src/skills/loadSkillsDir.ts Skill loader Bridges markdown skill files into executable prompt commands.
src/remote/RemoteSessionManager.ts Remote session controller Handles cloud session messaging and permission prompts.
src/bridge/bridgeMain.ts Remote-control bridge supervisor Runs long-lived environment registration and work polling.
src/utils/teleport.tsx Teleport flow Creates or resumes sessions across machines and repositories.

Cloud and remote architecture

The cloud-facing part of the repo is not a single subsystem. It is a stack of session transport, bridge control, and state handoff layers. 

Local CLI
  |
  +-- main.tsx
  |     |
  |     +-- REPL / QueryEngine / tools / MCP
  |
  +-- Remote session path
  |     |
  |     +-- remote/RemoteSessionManager.ts
  |     +-- remote/SessionsWebSocket.ts
  |     +-- remote/sdkMessageAdapter.ts
  |
  +-- Direct connect path
  |     |
  |     +-- server/directConnectManager.ts
  |
  +-- Remote-control bridge path
  |     |
  |     +-- bridge/bridgeMain.ts
  |     +-- bridge/createSession.ts
  |     +-- bridge/replBridge.ts
  |
  +-- Teleport path
        |
        +-- utils/teleport.tsx
        +-- utils/teleport/api.ts
        +-- services/api/sessionIngress.ts

Remote session

Used when the REPL attaches to a cloud session. Messages come over WebSocket and are adapted back into local REPL message types.

Direct connect

A simpler WebSocket path that forwards structured SDK messages and permission requests directly to a remote endpoint.

Remote control bridge

A long-running environment bridge that polls for work, spawns or resumes sessions, heartbeats them, and keeps web/mobile control alive.

Teleport

A session handoff path that validates git state, creates or resumes remote sessions, and restores the branch or transcript.

Managed settings

Enterprise settings can be fetched remotely and applied before other systems initialize, which affects policy, MCP, and auth.

MCP

MCP is the extension spine. The client layer supports stdio, SSE, streamable HTTP, WebSocket, and SDK in-process transports.

Current state

What is solid

The repo contains real core logic for startup, REPL rendering, query execution, tool orchestration, MCP integration, plugin loading, skills, auth, and cloud session flows.

What is incomplete

Several generated or extracted files are missing, some native or private integrations only have compatibility shims, and the type surface is out of sync with the installed dependency graph.

What is intentionally disabled

All feature flags are forced off by shims/bun-bundle.ts, so internal or Anthropic-only paths stay dead unless they are restored deliberately.

Release readiness

This is now a buildable developer artifact, not a production release. It is useful for study, customization, and targeted salvage, but not for shipping unchanged.

Verification snapshot

  • bun install passed.
  • bun run build passed after wiring local file-based stub packages for @ant/claude-for-chrome-mcp, @ant/computer-use-*, color-diff-napi, and modifiers-napi.
  • bun run typecheck failed with 4,469 TypeScript errors.
  • The largest error families were: TS7006 (2,087), TS2307 (535), TS2339 (470), and TS2305 (410).
  • The most common missing-module failures were ../../types/message.js (81), ../types/message.js (71), ./types.js (51), src/types/message.js (20), and ../../types/tools.js (15).

20 improvements

  1. P0: Add smoke coverage for the local stub package layer. The bundle now resolves the private and native placeholder modules, but the stubs are hand-maintained and can drift from the import surface expected by the runtime.
  2. P0: Replace fallback native shims with explicit capability detection. color-diff-napi and modifiers-napi now resolve, but the current placeholders silently degrade behavior. The runtime should announce unavailable features and select TS fallbacks intentionally.
  3. P0: Generate and commit src/entrypoints/sdk/controlTypes.ts. The code imports ./sdk/controlTypes.js from many places, but only controlSchemas.ts exists. The protocol surface is incomplete without the generated types.
  4. P0: Restore src/types/message.ts. Message types are imported all over the runtime, UI, and cloud layers. Their absence alone causes a large fraction of the typecheck failures.
  5. P0: Restore src/types/tools.ts and related shared type files. Tool progress and transport types are missing, which breaks tool UIs, structured IO, and process-user-input helpers.
  6. P0: Restore or remove other dangling shared modules. Missing files such as src/utils/secureStorage/types.ts, assistant helpers, and transport helper files should either be recreated or fully compiled out of the external build.
  7. P0: Finish or fully fence off contextCollapse. Only src/services/contextCollapse/index.ts exists, but the repo still imports operations.js and persist.js. That makes the feature half-stubbed and half-live.
  8. P1: Decide whether the standalone release metadata should stay and wire it to a real distribution flow. The build now defines MACRO.PACKAGE_URL, MACRO.NATIVE_PACKAGE_URL, and MACRO.VERSION_CHANGELOG, but they still point to a placeholder release story instead of a maintained updater pipeline.
  9. P1: Decide whether version enforcement should exist and implement it cleanly. src/utils/autoUpdater.ts short-circuits assertMinVersion() immediately, which makes the rest of the minimum-version path dead code.
  10. P1: Pin a dependency set that matches the leaked source. The current checkout shows type incompatibilities in OpenTelemetry, MCP, and other libraries. A compatibility matrix or lockfile audit is needed.
  11. P1: Handle react/compiler-runtime intentionally. Roughly 395 files import the compiler runtime helper. The repo needs either the right typings and transform pipeline, or a conversion back to normal authored TSX.
  12. P1: Split src/main.tsx into domain modules. It currently mixes CLI parsing, bootstrapping, remote flows, resume logic, and command wiring in one huge file, which slows onboarding and raises change risk.
  13. P1: Split src/screens/REPL.tsx into smaller view-model slices. The REPL is the operator surface and currently does too much: messaging, tasks, permission dialogs, bridge state, IDE hooks, and notifications.
  14. P1: Unify the cloud transport layer. RemoteSessionManager, SessionsWebSocket, DirectConnectSessionManager, and the bridge stack all solve overlapping connection and message-routing problems differently.
  15. P1: Add reconnect, heartbeat, and backoff to direct connect. The direct-connect manager is much thinner than the bridge and CCR session managers. It should share the same resilience behavior.
  16. P1: Consolidate tool orchestration. The repo has both StreamingToolExecutor and toolOrchestration.ts. The concurrency and cancellation behavior should come from one path so fixes land once.
  17. P2: Cache heavyweight provider clients. src/services/api/client.ts already carries a TODO about reusing GoogleAuth. The same mindset should apply to other expensive auth and provider objects.
  18. P2: Add CI gates that reflect reality. The repo needs automated install, build, typecheck, and smoke tests. Right now the current failure set is easy to miss until someone tries a fresh checkout.
  19. P2: Add regression tests for remote-control, teleport, MCP, and permissions. Those are the highest-risk paths because they mix auth, filesystem state, session transport, and tool execution.
  20. P2: Make the public-facing docs and README operational instead of historical. The current README is leak-centered. The repo needs a product-facing explanation of architecture, setup, cloud features, and limitations.

Hosting this documentation

This site is plain static HTML and CSS. You can host it as-is from the repository /docs directory with GitHub Pages, Netlify, Cloudflare Pages, S3, or any static web server.

  • GitHub Pages: publish the repository docs/ folder.
  • Local preview: python3 -m http.server 8080 --directory docs.
  • No build step is required for the documentation site itself.