Documentation

Source Map

A practical map for finding the real implementation behind CLI commands, API routes, TUI views, mobile flows, providers, plugins, and storage.

Overview

The main runtime lives in packages/nikcli/src. The repo is a Bun monorepo, so related packages also matter: packages/sdk/js for generated client types, packages/plugin for plugin contracts, packages/mobile for the Expo app, packages/web for this docs site, packages/llm for route-based LLM providers, and packages/remote for remote execution support.

This map is meant for tracing behavior from a symptom to the source. Start at the command or route entry, then follow service imports into the domain module.

Top-level entry

packages/nikcli/src/index.ts registers every CLI command with yargs, initializes global directories, initializes logging, sets AGENT=1 and NIKCLI=1, and catches fatal errors for user-facing formatting.

Terminal

bash

bun run --cwd packages/nikcli --conditions=browser src/index.ts --help
bun run --cwd packages/nikcli --conditions=browser src/index.ts serve --help
bun run --cwd packages/nikcli --conditions=browser src/index.ts mcp --help

Need	Start here	Then inspect
Command registration	`src/index.ts`	`src/cli/cmd/*.ts`
Global paths	`src/@nikcli-ai/util/global`	`NIKCLI_DATA_DIR`, XDG/AppData rules.
Logging	`@nikcli-ai/util/log`	`--print-logs`, `--log-level`.
Error formatting	`src/cli/error.ts`	Command-specific thrown errors.

Runtime domains

Entry

CLI and TUI

src/cli/cmd contains commands. src/cli/cmd/tui contains the OpenTUI/Solid renderer, worker RPC, routes, dialogs, plugins, and contexts.

HTTP

Server

src/server/server.ts owns middleware and route mounting. src/server/httpapi owns classic routes. src/server/httpapi owns typed route groups.

Agent

Sessions

src/session owns session lifecycle, prompt execution, LLM normalization, messages, status, revert, compaction, todo, and stats.

Tools

Extensions

src/plugin, src/mcp, src/connectors, src/skill, and src/tool expose extra capabilities to agents.

CLI command map

Every public command is imported and registered in src/index.ts.

Command	File	Domain
Default TUI	`cli/cmd/tui/thread.ts`	Worker RPC, SDK fetch, OpenTUI app.
`run`	`cli/cmd/run.ts`	Headless prompt execution.
`serve`	`cli/cmd/serve.ts`	General HTTP API server.
`mobile`	`cli/cmd/mobile.ts`	Mobile host, pairing, token list/revoke.
`remote`	`cli/cmd/remote.ts`	Terminal remote plus optional mobile host.
`mcp`	`cli/cmd/mcp.ts`	MCP config, OAuth, list, debug, logout.
`connectors`	`cli/cmd/connectors.ts`	External service config and credentials.
`plugin` / `plug`	`cli/cmd/plug.ts`	Plugin install, manifest read, config patch.
`models`	`cli/cmd/models.ts`	Provider/model catalog.
`debug`	`cli/cmd/debug`	Config, LSP, skill, snapshot, search, file utilities.
`routine`	`cli/cmd/routine.ts`	Routine CRUD, run, pause, resume.
`account`	`cli/cmd/account.ts`	Local account management.

Server map

Server behavior starts in src/server/server.ts. The exact route order matters: share routes, user auth middleware, server auth, CORS, /global, workspace context, /doc, typed bridge, then classic route groups.

Feature	Classic route	Typed route where present
Session	`server/httpapi/session.ts`	`server/httpapi/session.ts`
File	`server/httpapi/file.ts`	`server/httpapi/file.ts`
Provider	`server/httpapi/provider.ts`	`server/httpapi/provider.ts`
MCP	`server/httpapi/mcp.ts`	`server/httpapi/mcp.ts`
Config	`server/httpapi/config.ts`	`server/httpapi/config.ts`
Workspace	`server/httpapi/workspace.ts`	`server/httpapi/workspace.ts`
Question	`server/httpapi/question.ts`	`server/httpapi/question.ts`
Permission	`server/httpapi/permission.ts`	`server/httpapi/permission.ts`
Mobile	`server/httpapi/mobile.ts`	Classic only.
Analytics	`server/httpapi/analytics.ts`	Classic only.

Session and LLM map

Need	File	What to look for
Create/list/update/remove	`session/index.ts`	`Session.Service` methods and storage keys.
Prompt execution	`session/prompt.ts`	Tool setup, system prompt assembly, request loop.
LLM provider hot path	`session/llm.ts`	Message normalization, headers, provider transforms, tool conversion.
Native provider runtime	`session/llm/native-runtime.ts`	`@nikcli-ai/llm` route-based streaming for supported providers.
Messages and parts	`session/message-v2.ts`	Message/part persistence and retrieval.
Status	`session/status.ts`	Busy, retry, idle state.
Diff and revert	`session/summary.ts`, `session/revert.ts`	File diff summaries and revert/unrevert actions.
Stats	`session/stats.ts`	Token/cost/session aggregate data.

Storage and config map

Config and storage are separate. Config is resolved from well-known remote config, global files, custom file env, project files, inline env content, and config directories. Storage is durable JSON under Global.Path.data/storage plus SQLite/Drizzle databases under Global.Path.data.

Need	File	Notes
Global paths	`@nikcli-ai/util/global`	XDG/AppData resolution, `NIKCLI_DATA_DIR`, cache version.
Config loading	`config/config.ts`	Merge order, plugin/command/agent loading, legacy tools migration.
Config paths	`config/paths.ts`	Project file discovery, directory list, JSONC substitution.
TUI config	`config/tui.ts`, `config/tui-schema.ts`	Keybinds, scroll, mouse, layout config.
JSON store	`database/database.ts`	Read/write/update/list/transaction, locks, cache, migrations.
SQLite	`database/database.ts`	Drizzle client, WAL, migrations, PRAGMAs.

Extension map

Extension type	Source	Runtime hook
Server plugin	`plugin/index.ts`	Internal plugins, configured plugins, built-ins, auth hooks, tool hooks, event hooks.
TUI plugin	`packages/tui/src/plugin`	Command, route, dialog, sidebar, and keybind registration.
MCP	`mcp/index.ts`	Local stdio and remote HTTP/SSE clients converted into agent tools.
Connectors	`connectors/index.ts`, `connectors/registry.ts`	External service status, health checks, dynamic tools, prompts.
Skills	`skill/skill.ts`	Skill discovery from config directories and external skill folders.
Built-in tools	`tool/registry.ts`	Model and flag gated tool set for sessions.

TUI map

The TUI starts in cli/cmd/tui/thread.ts, creates a worker from cli/cmd/tui/worker.ts, then renders packages/tui/src/app.tsx. With no network options it uses direct RPC fetch and event source. With host/port options it starts a real HTTP server and talks through the SDK.

Area	Files
Route state	`packages/tui/src/context/route.tsx`
Session route	`packages/tui/src/routes/session/index.tsx`
Workspace route	`packages/tui/src/routes/workspace`, `routes/changes`, `routes/tree`, `routes/git-graph`, `routes/github`
Command palette	`packages/tui/src/component/dialog-command.tsx`
Remote control	`server/httpapi/tui.ts`, `packages/tui/src/event.ts`
Plugin runtime	`packages/tui/src/plugin/runtime.ts`, `plugin/api.tsx`

Mobile map

The Expo app lives in packages/mobile, while the host API lives in packages/nikcli/src/server/httpapi/mobile.ts and helpers under packages/nikcli/src/mobile.

Need	Host source	App source
Pairing tokens	`src/mobile/auth.ts`, `routes/mobile.ts`	`packages/mobile/app/connect.tsx`
Session streaming	`routes/mobile.ts`	`packages/mobile/hooks/use-session-stream.ts`
GitHub repos	`src/mobile/github-repo.ts`	`packages/mobile/app/(app)/repos`
Routines	`src/mobile/routine.ts`	`packages/mobile/app/(app)/routines`
Terminal	`routes/mobile.ts`, `src/pty`	`packages/mobile/app/(app)/terminal`
Settings	`routes/mobile.ts`, config/provider/MCP/connectors services	`packages/mobile/app/(app)/settings`

Generated and package map

Package	Purpose	When to inspect
`packages/sdk/js`	Generated JavaScript SDK for server APIs.	After endpoint contract changes or SDK type failures.
`packages/plugin`	Plugin API package and TUI plugin contracts.	When implementing or debugging plugin manifest targets.
`packages/llm`	Route-based LLM provider package used by native runtime.	When provider streaming behavior differs from AI SDK path.
`packages/mobile`	Expo mobile application.	When a host route is correct but app behavior differs.
`packages/web`	Astro docs and dashboard pages.	When editing docs, dashboard, or public web pages.
`packages/remote`	Remote execution support.	When terminal remote or cloud relay behavior changes.
`packages/inference`	Inference provider/gateway package.	When nikcli-inference provider catalog or routing changes.
`packages/http-recorder`	HTTP recording utilities.	When fixture or provider request recording changes.

How to trace a feature

Find the entry: command in src/index.ts, route in server.ts, or UI route in tui/context/route.tsx.
Read the domain service imported by that entry. Route files usually call services from session, provider, config, mcp, connectors, or workspace.
Check config and flags. Many features are enabled by config fields plus environment flags from @nikcli-ai/util/flag.
Check storage. Durable behavior usually writes through Storage.Service or a SQLite helper.
For client behavior, trace generated SDK types in packages/sdk/js/src/httpapi/generated and UI code in packages/mobile or TUI route files.

Terminal

bash

rg -n "route-or-command-name" packages/nikcli/src
rg -n "operationId|HttpApiEndpoint|get\\(|post\\(" packages/nikcli/src/server
rg -n "Config\\.Service|Provider\\.Service|Session\\.Service" packages/nikcli/src

Directory table

Directory	Purpose
`account`	Local user account records and auth helpers.
`acp`	Agent Client Protocol integration.
`agent`	Agent definitions, prompts, generated agent metadata, and selection.
`analytics`	Usage and session analytics aggregation.
`auth`	Provider and external auth storage used outside connector-specific auth.
`background`	Background task runner and status.
`brain`	Brain scheduler, consolidation, and long-term context features.
`bus`	Event bus definitions used by server, TUI, sessions, MCP, and permissions.
`chatbot`	Slack, Discord, Teams, Google Chat, Linear, and GitHub bot adapters.
`cli`	Yargs command definitions, OpenTUI app, local UI, network helpers.
`command`	Command templates, generated commands, and prompt commands.
`config`	Config schema, path discovery, JSONC parsing, migrations, TUI config.
`connectors`	External service connector status, credentials, tools, and operations.
`delegation`	Background delegation manager and parent/worker ownership.
`env`	Environment read/write helpers for provider code.
`file`	File listing, search, content, status, and time helpers.
`filesystem`	Effect filesystem helpers and compatibility wrappers.
`flag`	Environment flag parsing and dynamic flag getters.
`format`	Formatter detection and execution.
`git`	Git helpers and command wrappers.
`global`	Global data/cache/config/state/log/bin/repo paths and initialization.
`ide`	IDE detection and extension install helpers.
`image`	Image generation provider and model selection.
`installation`	Version, channel, update, and install/runtime metadata.
`locale`	Language, region, timezone, currency, and locale resolution.
`lsp`	Language server registry, lazy clients, diagnostics, symbols, references.
`mcp`	Model Context Protocol clients, OAuth, tools, prompts, resources.
`mobile`	Mobile auth, routines, Expo helpers, GitHub repo import, project detection.
`monitor`	Long-lived process monitoring and cancellation.
`permission`	Permission rules, pending requests, persisted always approvals.
`plugin`	Server plugins, auth plugins, installer, package manifest detection.
`project`	Project detection, instance context, VCS metadata.
`provider`	Provider catalog, auth, AI SDK adapters, model cache, transformations.
`pty`	Pseudo-terminal sessions and websocket I/O.
`question`	Interactive question prompts and replies.
`sandbox`	Sandbox and external directory checks for tool execution.
`scheduler`	Scheduled routine helpers.
`server`	Hono app, route groups, typed HttpApi bridge, proxying, mDNS.
`session`	Session records, messages, prompt execution, summaries, revert, stats.
`share`	Public share creation and public data retrieval.
`skill`	Skill discovery, loading, and prompt material.
`snapshot`	Snapshot and diff tracking for file changes.
`storage`	JSON storage service, locks, migrations, SQLite/Drizzle helpers.
`tool`	Built-in tool registry, definitions, prompts, and execution wrappers.
`util`	Shared utilities such as logs, queues, locks, wildcard, timeout, process helpers.
`workspace`	Workspace records, adaptors, remote/local targets, session proxy.
`worktree`	Git worktree creation, reset, and removal helpers.