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).
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 and the
Vercel AI SDK (ai
package) for streaming, and exposes a uniform LLMClient service regardless of
which backend is in use.
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.
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.
Protocols
Wire-protocol adapters that own body construction, schema validation, and stream
parsing: anthropic-messages, openai-chat,
openai-responses, bedrock-converse, and
gemini.
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.
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.
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.
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.
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.
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.
@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.). |