## 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.