# Getting Started

A source-of-truth overview of nikcli across the CLI, server, connectors, and mobile app.

## Install & Run

nikcli is a fork of OpenCode

nikcli is an independent fork of [OpenCode](https://github.com/anomalyco/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](https://github.com/nikcli/nikcli), 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](/docs/routines), and localizes both its interface and the model's replies. The CLI entrypoint is `packages/nikcli/src/index.ts`.

Terminal · macOS / Linux

bash 

```
curl -fsSL https://nikcli-ai.dev/install | bash
```

$ shell · paste into your terminal

PowerShell · Windows

powershell 

```
irm https://nikcli-ai.dev/install.ps1 | iex
```

Terminal

bash 

```
nikcli
```

$ shell · paste into your terminal

Install location

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

Runtime

For local development in this repo, run `bun dev` inside `packages/nikcli`.

## Architecture Snapshot

Interface

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

Core

### Session Engine

Sessions, messages, tool parts, sharing, and todo state live under `packages/nikcli/src/session/`.

Execution

### Tools & Permissions

The public tool surface is defined in `packages/nikcli/src/tool/registry.ts` and guarded by `packages/nikcli/src/permission/`.

Services

### Server + API

HTTP and SSE endpoints for TUI, companion, connectors, and mobile are built in `packages/nikcli/src/server/`.

Automation

### Connectors

External service connectors and auth live under `packages/nikcli/src/connectors/`.

Companion

### Mobile App

The Expo app in `packages/mobile` streams sessions, approvals, tool output, GitHub worktrees, and notifications from the host server.

## Platform Surfaces

[

Commands

### CLI Reference

Covers the default TUI flow plus `goal`, `routine`, `serve`, `remote`, `companion`, `mobile`, `connectors`, model, locale, and diagnostics commands.

Open reference →

](/docs/cli)[

Browser

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

Open reference →

](/docs/web-app)[

Host + app

### Mobile

Documents host pairing, session streaming, approvals, notifications, offline retry, and the Tophat config feature.

Open reference →

](/docs/mobile)[

Walkthroughs

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

Open reference →

](/docs/guides)[

Extend

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

Open reference →

](/docs/build)[

HTTP

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

Open reference →

](/docs/api)[

Monorepo

### Packages & Suite

`packages/nikcli` is the base; supporting packages include `@nikcli-ai/llm`, `http-recorder`, the SDK, mobile, and web.

Open reference →

](/docs/packages)

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

[

packages/nikcli

### Core runtime

Commands, agents, sessions, tools, connectors, sharing, storage, sync, and HTTP routes.

Open reference →

](/docs/architecture)[

packages/mobile + packages/web

### Supporting surfaces

Mobile session control, teleport, session artifacts, workspace switcher, and the docs experience itself.

Open reference →

](/docs/mobile)

## What's new

Recent releases added the [sync subsystem](/docs/sync) (event journal, projections, idempotent outbox, remote hub), the macOS [Island plugin](/docs/island) (notch UI), new TUI feature plugins ([Brain](/docs/brain), Browser, ChatBot, [Computer](/docs/computer-use), DeepSec, Observability), and several mobile sheets (teleport, session artifacts, workspace switcher). The most recent release also extracted three sibling automation engines — [computer-use](/docs/computer-use), [browser-control](/docs/browser-control), and [terminal-control](/docs/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](/docs/brand) reference.

[

New package

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

Open reference →

](/docs/computer-use)[

New package

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

Open reference →

](/docs/browser-control)[

New package

### Terminal-control engine

`@nikcli-ai/terminal-control`: native termctrl driver, `.termctrl` recordings, ANSI/JSON/PNG/SVG/video renderers, evidence bundles.

Open reference →

](/docs/terminal-control)[

Long-term memory

### Brain subsystem

Hourly scheduler, model picker, configurable consolidation session, and the `memory.instruction.md` file under `.github/instructions/`.

Open reference →

](/docs/brain)[

macOS notch

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

Open reference →

](/docs/island)[

Opt-in hub

### Sync subsystem

Local event log, typed projections, cold-start snapshots, idempotent outbox, remote hub transport.

Open reference →

](/docs/sync)[

TUI surface

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

Open reference →

](/docs/tui)[

Mobile

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

Open reference →

](/docs/mobile)[

Mobile

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

Open reference →

](/docs/mobile)[

Brand

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

Open reference →

](/docs/brand)[

TUI surface

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

Open reference →

](/docs/permissions#modes)

## Next Steps

Ready to roll

Start with [CLI Reference](/docs/cli), then configure providers and connectors in [Configuration](/docs/configuration).

---

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