# Packages & Suite

nikcli is a monorepo. packages/nikcli is the core CLI/TUI/server; the packages below provide supporting infrastructure, provider integrations, and surface-area extensions.

## Overview

The nikcli monorepo lives under `packages/`. The base product is `packages/nikcli` — the CLI binary, TUI, agent runtime, session storage, HTTP server, and built-in tool registry. Every other package is a supporting layer: provider infrastructure (`llm`), test tooling (`http-recorder`), SDKs, native surfaces (desktop, mobile), and hosted services (cloud, inference, slack).

Dependency direction

`packages/nikcli` depends on `@nikcli-ai/llm` for all LLM traffic. `@nikcli-ai/llm`'s test suite depends on `@nikcli-ai/http-recorder` to replay provider responses without live network calls. Neither recorder nor llm depends back on `packages/nikcli`.

## @nikcli-ai/llm

`packages/llm` is the multi-provider LLM client library that handles every inference request nikcli makes. It is built on [Effect](https://effect.website) and the [Vercel AI SDK](https://sdk.vercel.ai) (`ai` package) for streaming, and exposes a uniform `LLMClient` service regardless of which backend is in use.

packages/llm/src/route

### Route system

A _Route_ composes four orthogonal axes — Protocol, Endpoint, Auth, and Framing — into a typed, registerable unit. `LLMClient` resolves the correct route from a `ModelRef` at call time.

packages/llm/src/providers

### Providers

Named provider modules for Anthropic, OpenAI, Azure, Amazon Bedrock, Google Gemini, GitHub Copilot, Cloudflare, OpenRouter, xAI, and the built-in `nikcli-inference` gateway. Each exports a typed `model()` factory.

packages/llm/src/protocols

### Protocols

Wire-protocol adapters that own body construction, schema validation, and stream parsing: `anthropic-messages`, `openai-chat`, `openai-responses`, `bedrock-converse`, and `gemini`.

packages/llm/src/tool-runtime.ts

### Tool runtime

Agentic tool-use loop built on top of `LLMClient.stream`. Executes tool calls, accumulates results, and re-submits until a stop condition is met or the step limit is reached.

### How nikcli consumes @nikcli-ai/llm

`packages/nikcli/src/provider/llm-client.ts` creates and exports the Effect `Layer` for `LLMClient`:

```
// packages/nikcli/src/provider/llm-client.ts
import { LLMClient, RequestExecutor } from "@nikcli-ai/llm/route"

export const defaultLayer = Layer.suspend(() =>
  LLMClient.layer.pipe(Layer.provide(RequestExecutor.defaultLayer))
)
```

The session LLM pipeline in `src/session/llm/` and the provider registry in `src/provider/provider.ts` then use `LLMClient.stream` / `LLMClient.generate` to drive all model calls, and import provider model factories (e.g. `Anthropic.model()`, `OpenAI.model()`) from `@nikcli-ai/llm/providers` to build typed `ModelRef` values from user config.

### Key exports

| Export path | What it provides |
| --- | --- |
| `@nikcli-ai/llm` | `LLMClient`, `LLMCore`, schema types (`LLMRequest`, `LLMResponse`, `ModelRef`, etc.), `Tool` helpers, `Runtime` |
| `@nikcli-ai/llm/route` | `LLMClient` service + Effect layer, `Route.make`, `RequestExecutor` |
| `@nikcli-ai/llm/providers` | All named provider modules re-exported; individual providers also available at `@nikcli-ai/llm/providers/anthropic`, `.../openai`, etc. |
| `@nikcli-ai/llm/protocols/<name>` | Individual protocol adapters: `anthropic-messages`, `openai-chat`, `openai-responses`, `bedrock-converse`, `gemini`, `openai-compatible-chat` |
| `@nikcli-ai/llm/core` | Thin wrapper around the Vercel AI SDK `streamText` for cases that bypass the route system |
| `@nikcli-ai/llm/provider` | `Provider.make` — typed factory for declaring a new provider definition |

## @nikcli-ai/http-recorder

`packages/http-recorder` is a record-and-replay HTTP fixture library written with Effect. It intercepts `HttpClient` calls, serialises request/response pairs into versioned JSON _cassettes_, and plays them back deterministically in tests — eliminating live network calls while keeping provider protocol coverage.

It also handles WebSocket interactions: a cassette can contain both `http` and `websocket` interaction records in the same file.

packages/http-recorder/src/cassette.ts

### Cassette storage

Effect `Service` and `Layer` for reading, writing, appending, and listing cassette files under a configurable directory. Cassettes are `version: 1` JSON files containing an array of typed interactions.

packages/http-recorder/src/effect.ts

### Record / replay layer

`cassetteLayer(name, options)` returns an Effect `Layer` that replaces `HttpClient`. In `record` mode it proxies the real network and writes cassettes; in `replay` mode it matches recorded interactions and returns the saved response.

packages/http-recorder/src/redaction.ts

### Secret redaction

Scans cassettes for patterns that resemble API keys, auth tokens, or other secrets before writing. If findings are detected the write is refused and the caller receives a descriptive error.

packages/http-recorder/src/matching.ts

### Matching & diff

Configurable request-matching strategy (default: URL + method + body hash). A `sequential` dispatch mode replays interactions in order. Mismatch errors include a human-readable diff of expected vs. actual request fields.

### Modes

| Mode | Behaviour |
| --- | --- |
| `replay` (default) | Loads the cassette from disk and returns the saved response for each matched request. Fails with a clear error if the cassette is missing or no interaction matches. |
| `record` | Forwards requests to the real upstream, captures responses, and appends them to the cassette. Blocked if the response body contains detected secrets. |
| `passthrough` | Skips cassette logic entirely and forwards all requests to the real network. Useful for one-off exploration without recording. |

### Usage in @nikcli-ai/llm tests

The llm package's test helpers (`packages/llm/test/recorded-test.ts`, `recorded-websocket.ts`) import `HttpRecorder` from `@nikcli-ai/http-recorder` and wrap each provider test case in a `cassetteLayer` pointing at `packages/llm/test/fixtures/recordings/`. Running with `RECORD=true` refreshes the fixtures against live providers; the default CI run replays them.

Setting up recording

`packages/llm` ships a helper script: `bun run setup:recording-env` (`script/setup-recording-env.ts`) that prepopulates the required provider API keys before a record pass.

## Full Package Table

Packages without a `package.json` at their root (e.g. `packages/sdk` which nests `packages/sdk/js`, or `packages/extensions/zed` which is a Zed extension manifest) are listed by their published package name. The `packages/console/` tree publishes five sibling packages under the `@nikcli-ai/console-*` scope; the `packages/containers/` tree ships prebuilt Docker images rather than a single npm package.

The three automation engines

`@nikcli-ai/computer-use`, `@nikcli-ai/browser-control`, and `@nikcli-ai/terminal-control` are sibling engines that share the same CLI grammar (`start / info / recording / bundle`) and the same per-workspace background daemon pattern. Their `bundle` commands all produce the same artifact set (`screenshot.png`, `demo.mp4`, `preview.gif`, `manifest.json`, `pr.md`) so PR pipelines can treat them uniformly.

| Package | Path | Role |
| --- | --- | --- |
| `@nikcli-ai/nikcli` | `packages/nikcli` | Core CLI, TUI, agent runtime, session management, HTTP server, and all built-in tools. The primary deliverable. |
| `@nikcli-ai/llm` | `packages/llm` | Multi-provider LLM client: route-based model refs, protocol adapters (Anthropic, OpenAI, Gemini, Bedrock, and more), tool-use runtime, and Effect-native streaming. |
| `@nikcli-ai/http-recorder` | `packages/http-recorder` | Record-and-replay HTTP (and WebSocket) test fixture library used by @nikcli-ai/llm's provider test suite. |
| `@nikcli-ai/sdk` | `packages/sdk/js` | Public JavaScript/TypeScript SDK exposing the nikcli client, server utilities, cloud sync helpers, and generated API types. |
| `@nikcli-ai/plugin` | `packages/plugin` | TypeScript types and utilities for authoring nikcli plugins, including the PluginInput contract and tool-definition helpers. |
| `@nikcli-ai/inference` | `packages/inference` | Self-hosted OpenAI-compatible inference gateway that routes to 14 upstream providers, caches responses, and applies per-tier rate limiting. |
| `@nikcli-ai/inference-dashboard` | `packages/inference-dashboard` | Astro-based admin dashboard for the inference gateway, surfacing provider health, usage, and cache statistics. |
| `@nikcli-ai/cloud` | `packages/cloud` | Cloudflare-Workers backend providing JWT auth, device registration, encrypted session storage (D1), and WebSocket relay via Durable Objects. |
| `@nikcli-ai/remote` | `packages/remote` | WebSocket terminal-server that lets mobile and web clients access a running nikcli session remotely, with optional tunnel and QR-code pairing. |
| `@nikcli-ai/companion` | `packages/companion` | Companion server and UI for pairing remote clients with a local nikcli session. |
| `@nikcli-ai/desktop` | `packages/desktop` | Native desktop application built with Tauri v2, embedding the nikcli web UI in a platform-native shell. |
| `@nikcli-ai/enterprise` | `packages/enterprise` | SolidStart web application for enterprise deployments, providing a browser-based interface for managing nikcli teams and sessions. |
| `@nikcli-ai/slack` | `packages/slack` | Cloudflare Worker that connects a Slack workspace to a running nikcli server, supporting text and voice-message sessions. |
| `@nikcli-ai/ui` | `packages/ui` | Shared SolidJS component library (buttons, accordions, avatars, tool views) used by the app, enterprise, and desktop packages. |
| `@nikcli-ai/util` | `packages/util` | Lightweight utility helpers (array, binary, encoding, error, function) shared across workspace packages. |
| `@nikcli-ai/function` | `packages/function` | Minimal Hono-based HTTP function package providing a stub API entrypoint. |
| `@opentui/webrenderer` | `packages/webrenderer` | OpenTUI web-view renderer that bridges native browser runtime, WebViewController, and SolidJS bindings for embedded web views inside the TUI. |
| `@nikcli-ai/app` | `packages/app` | SolidJS single-page application shell used by desktop and companion, containing shared layout, context providers, and add-on entry points. |
| `@nikcli-ai/mobile` | `packages/mobile` | React Native / Expo companion app for iOS and Android that streams sessions over SSE and handles mobile-specific permissions. |
| `@nikcli-ai/web` | `packages/web` | Astro site that powers nikcli-ai.dev, the docs site, and the Studio dashboard. |
| `@nikcli-ai/computer-use` | `packages/computer-use` | Headless desktop-automation engine: daemon, sandbox/host backends, recording pipeline, PR-ready evidence bundles. Sibling of browser-control and terminal-control. |
| `@nikcli-ai/browser-control` | `packages/browser-control` | Headless browser-automation engine for Chromium pages: per-workspace daemon, recording pipeline, evidence bundles. Powers the browser tool. |
| `@nikcli-ai/terminal-control` | `packages/terminal-control` | Terminal-recording engine with native termctrl driver: .termctrl recordings, JSON/ANSI/PNG/SVG/video renderers, evidence bundles. |
| `@nikcli-ai/tui-image` | `packages/tui-image` | Image rendering primitives for TUI / OpenTUI terminals with Kitty, Sixel, iTerm2 and Unicode fallbacks. |
| `@nikcli-ai/sdk-next` | `packages/sdk-next` | Next-generation JavaScript SDK prototype. Lives next to @nikcli-ai/sdk; see that package for the stable surface. |
| `@nikcli-ai/auth` | `packages/auth` | Provider and external auth storage used outside connector-specific auth (distinct from per-connector and account-level auth). |
| `@nikcli-ai/identity` | `packages/identity` | Identity layer shared across the cloud surface, accounts, and mobile pairing. |
| `@nikcli-ai/httpapi-codegen` | `packages/httpapi-codegen` | Code generator for the typed HttpApi route groups consumed by the SDK. |
| `@nikcli-ai/bench-tui` | `packages/bench-tui` | Standalone test interface and benchmark dashboard for Bun packages — SolidJS over OpenTUI. |
| `@nikcli-ai/simulation` | `packages/simulation` | Driver + recording + protocol layer for the simulation harness used by browser, terminal and computer engines. |
| `@nikcli-ai/script` | `packages/script` | Cross-package CLI scripts and ops tooling — includes the Railway deploy script referenced from the mobile doc. |
| `@nikcli-ai/nikcli-island` | `packages/nikcli-island` | Swift package that ships NikcliIsland.app, the macOS notch HUD for live sessions. Outside the JS build graph. |
| `@nikcli-ai/containers` | `packages/containers` | Prebuilt GitHub Actions container images: base, bun-node, rust, tauri-linux, publish. |
| `@nikcli-ai/extensions/zed` | `packages/extensions/zed` | Zed editor extension that wires nikcli as an agent server. |
| `@nikcli-ai/console-app` | `packages/console/app` | Console-suite Vite app shell for the hosted admin surface. |
| `@nikcli-ai/console-core` | `packages/console/core` | Console-suite shared core: AWS SDK helpers, SST infra glue, and JSX-email rendering. |
| `@nikcli-ai/console-function` | `packages/console/function` | Console-suite Cloudflare Worker functions exposed under the console surface. |
| `@nikcli-ai/console-mail` | `packages/console/mail` | Console-suite transactional-email worker built on @jsx-email. |
| `@nikcli-ai/console-resource` | `packages/console/resource` | Console-suite Cloudflare resource bindings (KV, R2, Durable Objects, etc.). |

---

Source: https://nikcli-ai.dev/docs/packages