Build

Three ways in

nikcli is a CLI, a server and a terminal UI that all sit on the same typed HTTP API. That means there is no privileged inside: the TUI reaches the session engine through the same endpoints your code can. Which path you take depends on where your code should run.

Extend — plugins

A plugin is a module nikcli loads at startup. It receives a client bound to the running instance and returns a set of hooks. @nikcli-ai/plugin is the contract package; it carries only types and the tool() helper, so it adds nothing to your runtime.

import type { Plugin } from "@nikcli-ai/plugin"
import { tool } from "@nikcli-ai/plugin/tool"

export const MyPlugin: Plugin = async ({ client, directory, $ }) => ({
  tool: {
    deploy: tool({
      description: "Deploy the current branch to staging",
      args: { branch: tool.schema.string().describe("branch to deploy") },
      async execute(args, ctx) {
        ctx.metadata({ title: `Deploying ${args.branch}` })
        const out = await $`./script/deploy.sh ${args.branch}`.text()
        return { title: "Deployed", output: out }
      },
    }),
  },

  async "tool.execute.before"(input, output) {
    if (input.tool === "bash") output.args.timeout = 120_000
  },
})

The hook surface is the interesting part. Beyond tool, a plugin can observe every server event, rewrite the parameters and headers of the model call (chat.params, chat.headers, chat.request), decide permissions (permission.ask), shape the shell environment (shell.env, shell.create.before), register an auth method or a whole provider, and transform the messages and system prompt before they reach the model.

TUI feature plugins are a separate runtime with its own contract (@nikcli-ai/plugin/tui): they add routes, sidebar panels, dialogs and keybinds to the terminal UI, and local ones hot-reload in place while it runs. See TUI Feature Plugins.

Connect — the client

@nikcli-ai/sdk is a typed client generated from the same OpenAPI document as the API reference, so every endpoint is a method and contract drift fails generation rather than surfacing as a runtime 404.

npm install @nikcli-ai/sdk

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient({
  baseUrl: "http://127.0.0.1:4096",
  directory: "/Users/me/project",
})

const { data: session } = await client.session.create({ title: "release notes" })
await client.session.prompt({
  sessionID: session!.id,
  parts: [{ type: "text", text: "Summarise what changed since v1.2.0" }],
})

Full walkthrough — auth, the result envelope, instance selection, streaming and errors — in Client.

Embed — in-process

The embedded host runs the server's request handler in memory. It opens no listener and does no network I/O, while keeping the same routing, middleware, handlers, codecs and errors as the network client — so code written against the client works unchanged against the embedded host.

import { NikCli } from "@nikcli-ai/sdk-next"
import { Effect } from "effect"

const program = Effect.gen(function* () {
  const nikcli = yield* NikCli.create({ directory: process.cwd() })
  return yield* Effect.promise(() => nikcli.session.list())
})

It also lets you register tools directly, which the HTTP path cannot do — a tool is executable code and does not travel over a wire. See Embedded SDK.

Which one do I want?

What people build

Source anchors