gogadmin
/
claudecode


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548
							<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Workbench CLI Audit</title>
    <meta
      name="description"
      content="Architecture, current state, cloud runtime notes, and a 20-item improvement backlog for the reconstructed Workbench CLI repository."
    />
    <link rel="stylesheet" href="./styles.css" />
  </head>
  <body>
    <header class="hero">
      <div class="hero-inner">
        <p class="eyebrow">Static project documentation</p>
        <h1>Workbench CLI</h1>
        <p class="lede">
          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.
        </p>
        <div class="meta">
          <span>Audit date: 2026-03-31</span>
          <span>Source files in <code>src/</code>: 1,929</span>
          <span>Extracted files in <code>stubs/</code>: 493</span>
        </div>
        <div class="status-grid">
          <article class="status-card ok">
            <h2>Install</h2>
            <p><code>bun install</code> succeeds.</p>
          </article>
          <article class="status-card ok">
            <h2>Build</h2>
            <p>
              <code>bun run build</code> succeeds and emits
              <code>dist/cli.js</code>.
            </p>
          </article>
          <article class="status-card warn">
            <h2>Typecheck</h2>
            <p>
              <code>bun run typecheck</code> reports 4,469 TypeScript errors in
              this checkout.
            </p>
          </article>
          <article class="status-card info">
            <h2>Cloud Logic</h2>
            <p>
              Remote control, teleport, direct connect, and managed settings
              are all materially implemented.
            </p>
          </article>
        </div>
      </div>
    </header>

    <div class="page">
      <aside class="toc">
        <h2>Contents</h2>
        <nav>
          <a href="#overview">Overview</a>
          <a href="#flow">How it works</a>
          <a href="#files">Main files</a>
          <a href="#cloud">Cloud architecture</a>
          <a href="#state">Current state</a>
          <a href="#improvements">20 improvements</a>
          <a href="#hosting">Hosting</a>
        </nav>
      </aside>

      <main class="content">
        <section id="overview" class="panel">
          <h2>Overview</h2>
          <p>
            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.
          </p>
          <p>
            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.
          </p>
          <div class="summary-grid">
            <article>
              <h3>Architecture completeness</h3>
              <p>High. Most of the core execution, UI, tools, and cloud flows are present.</p>
            </article>
            <article>
              <h3>Build integrity</h3>
              <p>Medium. A fresh install now produces a working bundle, but the fallback shim layer is still fragile.</p>
            </article>
            <article>
              <h3>Type integrity</h3>
              <p>Low. The checkout currently fails typecheck at scale.</p>
            </article>
            <article>
              <h3>Cloud feature depth</h3>
              <p>Medium. Remote-control and teleport logic are real, but the release surface is incomplete.</p>
            </article>
          </div>
        </section>

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

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

        <section id="cloud" class="panel">
          <h2>Cloud and remote architecture</h2>
          <p>
            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.
          </p>
          <pre class="diagram">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</pre>
          <div class="summary-grid">
            <article>
              <h3>Remote session</h3>
              <p>
                Used when the REPL attaches to a cloud session. Messages come
                over WebSocket and are adapted back into local REPL message types.
              </p>
            </article>
            <article>
              <h3>Direct connect</h3>
              <p>
                A simpler WebSocket path that forwards structured SDK messages
                and permission requests directly to a remote endpoint.
              </p>
            </article>
            <article>
              <h3>Remote control bridge</h3>
              <p>
                A long-running environment bridge that polls for work, spawns or
                resumes sessions, heartbeats them, and keeps web/mobile control alive.
              </p>
            </article>
            <article>
              <h3>Teleport</h3>
              <p>
                A session handoff path that validates git state, creates or
                resumes remote sessions, and restores the branch or transcript.
              </p>
            </article>
            <article>
              <h3>Managed settings</h3>
              <p>
                Enterprise settings can be fetched remotely and applied before
                other systems initialize, which affects policy, MCP, and auth.
              </p>
            </article>
            <article>
              <h3>MCP</h3>
              <p>
                MCP is the extension spine. The client layer supports stdio,
                SSE, streamable HTTP, WebSocket, and SDK in-process transports.
              </p>
            </article>
          </div>
        </section>

        <section id="state" class="panel">
          <h2>Current state</h2>
          <div class="summary-grid">
            <article>
              <h3>What is solid</h3>
              <p>
                The repo contains real core logic for startup, REPL rendering,
                query execution, tool orchestration, MCP integration, plugin
                loading, skills, auth, and cloud session flows.
              </p>
            </article>
            <article>
              <h3>What is incomplete</h3>
              <p>
                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.
              </p>
            </article>
            <article>
              <h3>What is intentionally disabled</h3>
              <p>
                All feature flags are forced off by <code>shims/bun-bundle.ts</code>,
                so internal or Anthropic-only paths stay dead unless they are
                restored deliberately.
              </p>
            </article>
            <article>
              <h3>Release readiness</h3>
              <p>
                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.
              </p>
            </article>
          </div>

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

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

        <section id="hosting" class="panel">
          <h2>Hosting this documentation</h2>
          <p>
            This site is plain static HTML and CSS. You can host it as-is from
            the repository <code>/docs</code> directory with GitHub Pages, Netlify,
            Cloudflare Pages, S3, or any static web server.
          </p>
          <ul class="checklist">
            <li>GitHub Pages: publish the repository <code>docs/</code> folder.</li>
            <li>Local preview: <code>python3 -m http.server 8080 --directory docs</code>.</li>
            <li>No build step is required for the documentation site itself.</li>
          </ul>
        </section>
      </main>
    </div>
  </body>
</html>