Architecture

Overview

nikcli is a Bun monorepo centered on packages/nikcli. The CLI process initializes global paths and logging, resolves project instances, loads config through Effect layers, and then runs one of several front doors: the OpenTUI terminal app, one-shot commands, an HTTP server, workspace hosting, mobile hosting, companion UI, remote control, or automation flows. Most of those surfaces converge on the same session, provider, tool, permission, storage, and event services.

Package map

The repository is a Bun workspace. The most important boundary is that packages/nikcli owns the executable runtime, while sibling packages provide clients, UI shells, plugins, remote services, and companion surfaces.

bun install
bun run typecheck
bun test
bun run --cwd packages/nikcli dev
bun run --cwd packages/nikcli generate:httpapi-clients

CLI lifecycle

packages/nikcli/src/index.ts is the process entrypoint, and it is deliberately tiny: it installs a document shim and hands off to src/cli-main.ts. Keeping the two apart is what lets the compiled binary re-enter itself as a --browser-control-daemon / --computer-use-daemon host without paying for the whole CLI module graph first.

cli-main.ts builds the yargs CLI, installs global error handlers, initializes global paths and logging, sets AGENT=1 and NIKCLI=1, registers commands, and forces process exit to avoid hanging subprocesses.

1. Global initialization creates data, config, cache, state, log, bin, and repo paths.
2. Logging setup respects --print-logs, --log-level, and local development defaults.
3. Global flags are parsed before any command runs: --print-logs, --log-level, --island, and --auto (aliased as --yolo and --dangerously-skip-permissions, which set NIKCLI_AUTO_APPROVE so the TUI's worker thread sees it too).
4. Command registration wires ACP, MCP, ads, TUI thread/attach, run, goal, analytics, generate, debug, auth, account, artifact, agent, upgrade, quickstart, doctor, uninstall, serve, workspace-serve, web, heap, models, locale, stats, export/import, GitHub, PR, session, image/speak/brain model pickers, remote, teleport, companion, mobile, routine, mission, usage, plugin, sync, connectors, and chatbot commands. --attach is also a flag on run.
5. Failure formatting uses FormatError for known errors and points unknown errors at the log file.
6. Process exit runs in finally to avoid hanging child processes, especially external MCP servers.

Instance model

Runtime services are scoped to project instances rather than process globals wherever possible. Commands and server routes run inside an instance context that carries the active directory, worktree, config paths, and service layers. This is why the TUI worker can host a server, respond to SDK calls, and still dispose project state cleanly through Instance.disposeAll().

Server stack

packages/nikcli/src/server/server.ts owns the Bun.serve listener and server/server-router.ts owns the request pipeline. Every declared route is a typed effect/unstable/httpapi group under server/httpapi/, composed into one API in httpapi/public.ts and served through HttpApiBridge. There is no Hono layer and no server/routes/ directory. See Server & API.

Session runtime

Sessions are the main execution unit. The session layer persists metadata, messages, message parts, diffs, summaries, todos, goals, and share state; coordinates agent execution; publishes events; and exposes both SDK routes and internal service calls. The one-shot command, TUI, mobile host, remote control, workspace hosting, and server API all converge here.

LLM and providers

Provider configuration is split from the session hot path. provider/provider.ts builds provider and model metadata from bundled SDK adapters, models.dev, config providers, saved auth, dynamic providers such as Ollama and nikcli inference, and plugin-supplied auth or model loaders. session/llm.ts is where requests are actually shaped and sent.

Tools and permissions

Tools are available to agents through the tool registry and are guarded by the permission system where needed. Permissions are evaluated from rules, path patterns, and action defaults, with pending prompts published as bus events and persisted always-approvals stored under the project storage namespace. See Permission modes for the TUI presets (require_approval / approve_for_me / full_access / custom) that write the per-agent permission map.

Storage and state

All durable state lives in a single SQLite database, nikcli.db under Global.Path.data, reached through Drizzle. Each domain declares its tables in a *.sql.ts file, re-exported from src/database/schema.ts, and queries them through a repository namespace. See Storage.

Things that stay files do so because a file is the interface: config (nikcli.json), provider credentials (auth.json), markdown plans, snapshots, skills, commands, agents, and themes.

Events and sync

The server publishes typed events through bus definitions and exposes event streams to SDK clients. The TUI consumes them through SDKProvider, batches deliveries, and updates Solid stores. Mobile and companion surfaces consume the same event model over server routes.

1. Runtime module changes state, such as session update, message part append, permission request, or TUI command publish.
2. Bus event is published with a typed schema and payload.
3. Server event route streams it to SDK subscribers.
4. Client sync provider handles it and updates route, transcript, provider, permission, toast, or workspace state.
5. UI renders from synchronized state instead of manually polling each route.

Integrations

nikcli has three integration families: MCP servers, first-party connector registry entries, and plugins. MCP extends tool/resource/prompt surfaces. Connectors integrate named services and bot transports. Plugins can contribute auth, providers, commands, server hooks, and TUI routes.

Mobile and remote

Mobile hosting is a server route family, not the same feature as terminal remote control. The mobile host serves /mobile/* routes, validates bearer tokens from mobile_auth.db, streams sessions over SSE, handles permission replies, exposes routine and repository workflows, and remains compatible with hosted environments such as Railway when using the host path.

SDK boundary

The generated JavaScript SDK is the contract between server routes and clients. The TUI imports @nikcli-ai/sdk/httpapi even when running in-process; it swaps only the fetch/event transport. Web, mobile, companion, and external clients use the same conceptual surface.

Operational map

Use this map to decide where to start for common architecture questions.

Source anchors