Getting Started
A source-of-truth overview of nikcli across the CLI, server, connectors, and mobile app.
Install & Run
nikcli is an independent fork of OpenCode, the open source coding agent — full credit for the original project goes to its authors and contributors. nikcli is not affiliated with or endorsed by them, so please report anything you hit here on the nikcli repository, never on the upstream tracker.
nikcli is a Bun-based coding agent with a terminal UI, HTTP server, connector system, a
browser web app, a Studio dashboard, and a mobile companion app. It also runs autonomously
toward verifiable goals, schedules and API-triggers routines, and
localizes both its interface and the model's replies. The CLI entrypoint is
packages/nikcli/src/index.ts.
curl -fsSL https://nikcli-ai.dev/install | bashirm https://nikcli-ai.dev/install.ps1 | iexnikcli
Both installers drop the binary in ~/.nikcli/bin and add it to your PATH — set
NIKCLI_INSTALL_DIR to change that. On Windows the PowerShell installer also reads
NIKCLI_VERSION to pin a version and NIKCLI_NO_PATH=1 to leave PATH
untouched. Any platform can also install from npm with npm i -g nikcli-ai@latest.
For local development in this repo, run bun dev inside
packages/nikcli.
Architecture Snapshot
CLI + TUI
Commands are registered in packages/nikcli/src/index.ts. The default TUI and
worker flow live in packages/nikcli/src/cli/cmd/tui/.
Session Engine
Sessions, messages, tool parts, sharing, and todo state live under
packages/nikcli/src/session/.
Tools & Permissions
The public tool surface is defined in packages/nikcli/src/tool/registry.ts
and guarded by packages/nikcli/src/permission/.
Server + API
HTTP and SSE endpoints for TUI, companion, connectors, and mobile are built in
packages/nikcli/src/server/.
Connectors
External service connectors and auth live under
packages/nikcli/src/connectors/.
Mobile App
The Expo app in packages/mobile streams sessions, approvals, tool output,
GitHub worktrees, and notifications from the host server.
Platform Surfaces
CLI Reference
Covers the default TUI flow plus goal, routine, serve,
remote, companion, mobile, connectors,
model, locale, and diagnostics commands.
Web App & Studio
Drive sessions from the browser via nikcli web and the /app SPA,
or manage agents, sessions, MCP, and config from the /dashboard Studio.
Mobile
Documents host pairing, session streaming, approvals, notifications, offline retry, and the Tophat config feature.
Guides
Step-by-step: write a plugin from an empty file, copy from eight plugin recipes, drive the HTTP API with curl or the SDK, and stream a response as it is produced.
Build
Plugins that run inside the agent, the typed client that drives a running server, and the embedded host that runs nikcli in your own process.
API Reference
Every endpoint the server exposes, generated from its OpenAPI document: base URL, the authentication schemes, instance selection, streaming feeds, and all 346 operations grouped by resource.
Packages & Suite
packages/nikcli is the base; supporting packages include
@nikcli-ai/llm, http-recorder, the SDK, mobile, and web.
Codebase Roadmap
The runtime surface is split across three main packages: packages/nikcli for the
CLI and server, packages/mobile for the Expo app, and packages/web
for this documentation site.
Core runtime
Commands, agents, sessions, tools, connectors, sharing, storage, sync, and HTTP routes.
Supporting surfaces
Mobile session control, teleport, session artifacts, workspace switcher, and the docs experience itself.
What's new
Recent releases added the sync subsystem (event journal, projections,
idempotent outbox, remote hub), the macOS Island plugin
(notch UI), new TUI feature plugins (Brain, Browser, ChatBot,
Computer, DeepSec, Observability), and several mobile
sheets (teleport, session artifacts, workspace switcher). The most recent release also
extracted three sibling automation engines — computer-use,
browser-control, and
terminal-control — out of packages/nikcli
into first-class workspace packages. The brand wordmarks are now shared between web and
mobile — see the brand assets reference.
Computer-use engine
@nikcli-ai/computer-use: headless desktop-automation daemon, sandbox/host
backends, recording pipeline, PR-ready evidence bundles. Sibling of browser-control
and terminal-control.
Browser-control engine
@nikcli-ai/browser-control: per-workspace Chromium daemon with the same
CLI grammar and bundle format as computer-use and terminal-control.
Terminal-control engine
@nikcli-ai/terminal-control: native termctrl driver, .termctrl
recordings, ANSI/JSON/PNG/SVG/video renderers, evidence bundles.
Brain subsystem
Hourly scheduler, model picker, configurable consolidation session, and the
memory.instruction.md file under
.github/instructions/.
Island plugin
NikcliIsland.app and the bridge that mirrors session state into the file
contract it reads. Bidirectional: the notch can answer permission requests via
POST /permission/:requestID/reply.
Sync subsystem
Local event log, typed projections, cold-start snapshots, idempotent outbox, remote hub transport.
New TUI feature plugins
Brain (model + scheduler), Browser (computer-use), ChatBot (Slack / Discord / Teams / GChat / Linear / GitHub webhooks), Computer, DeepSec, and Observability are now first-class TUI plugins.
Teleport and artifacts
nikcli teleport ships a session (and optionally the working tree) to a
remote host, the mobile app exposes a teleport sheet, and session artifact viewer
surfaces URLs, HTML, SVG, and Mermaid previews inline.
Workspace switcher
The mobile app can browse workspaces from the host, swap the active directory, and deep-link into the right session in one tap.
Shared wordmark
Three PNG variants are now used consistently across the docs navbar, footer, dashboard
connect screen, and mobile app via a single source of truth in
packages/mobile/assets/.
Permission modes
The TUI command palette now exposes a Permissions dialog with three presets —
require_approval, approve_for_me (default), and full_access —
that write the per-agent permission map. A custom state surfaces
when an individual tool is changed by hand.
Next Steps
Start with CLI Reference, then configure providers and connectors in Configuration.