Documentation

Tools & Worktrees

Experimental surface: the tool registry, the resource list, plain git worktrees, and the managed worktrees that carry parent/child links.

Playground

Send these requests to your own running server. Values stay in this browser.

Not connected

Base URL Directory optional Bearer token optional

How this works

Start a server with nikcli serve --hostname 127.0.0.1 --port 4096. Requests go straight from this page to that address — the browser allows it because loopback counts as a secure origin, and the server allows it because nikcli-ai.dev is in its CORS allowlist.

To try things without touching your real sessions or config, start the server with NIKCLI_TEST_HOME pointed at a throwaway directory — see the guided tour.

Operations

13 endpoints, generated from the server's own OpenAPI document. Every path also accepts the directory and workspace query parameters that select which instance handles the request.

get	/experimental/tool/ids	tool.ids
get	/experimental/tool	tool.list
get	/experimental/worktree	worktree.list
post	/experimental/worktree	worktree.create
delete	/experimental/worktree	worktree.remove
post	/experimental/worktree/reset	worktree.reset
get	/experimental/resource	experimental.resource.list
get	/experimental/managed-worktree	managed-worktree.list
post	/experimental/managed-worktree	managed-worktree.create
delete	/experimental/managed-worktree	managed-worktree.remove
post	/experimental/managed-worktree/link	managed-worktree.link
get	/experimental/managed-worktree/children	managed-worktree.children
get	/experimental/managed-worktree/ancestors	managed-worktree.ancestors

get /experimental/tool/ids # tool.ids

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Responses

200 ToolIDs application/json

string[]

Example response captured

[
  "invalid",
  "question",
  "bash",
  "monitor",
  "read",
  "tree",
  "glob",
  "grep",
  "edit",
  "write",
  "multiedit",
  "task",
  "delegation",
  "context_collect",
  "context_related",
  "context_diagnostics",
  "memory_search",
  "generate_image",
  "artifact",
  "webfetch",
  "todowrite",
  "todoread",
  "create_goal",
  "get_goal",
  "update_goal",
  "websearch",
  "codesearch",
  "repo_clone",
  "repo_overview",
  "skill",
  "apply_patch",
  "lsp",
  "plan_exit",
  "plan_enter",
  "speak",
  "voice",
  "opentui",
  "plugin",
  "advisor",
  "delegator",
  "search_tools",
  "code_mode",
  "browser_control",
  "computer",
  "herdr"
]

SDK example

tool.ids

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

const client = createNikcliClient()
await client.tool.ids({
  ...
})

Try it

directory query workspace query

get /experimental/tool # tool.list

Parameters

Name	In	Type	Required
provider	query	string	required
model	query	string	required
directory	query	string	optional
workspace	query	string	optional

Responses

200 ToolList application/json

ToolListItem[]

Example response from schema

[
  {
    "id": "",
    "description": "",
    "parameters": null
  }
]

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

tool.list

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

const client = createNikcliClient()
await client.tool.list({
  ...
})

Try it

provider query · required model query · required directory query workspace query

get /experimental/worktree # worktree.list

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Responses

200 WorktreeList application/json

string[]

Example response from schema

[
  ""
]

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

worktree.list

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

const client = createNikcliClient()
await client.worktree.list({
  ...
})

Try it

directory query workspace query

post /experimental/worktree # worktree.create

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  name?: string | null
  branch?: string | null
  branchPrefix?: string | null
  baseBranch?: string | null
  remote?: string | null
  startCommand?: string | null
}

Responses

200 Worktree application/json

{
  name: string
  branch?: string | null
  directory: string
}

Example response from schema

{
  "name": "",
  "branch": "",
  "directory": ""
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

worktree.create

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

const client = createNikcliClient()
await client.worktree.create({
  ...
})

Try it

directory query workspace query

Request body application/json

delete /experimental/worktree # worktree.remove

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  directory: string
}

Responses

200 Success application/json

boolean

Example response from schema

false

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

worktree.remove

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

const client = createNikcliClient()
await client.worktree.remove({
  ...
})

Try it

directory query workspace query

Request body application/json

This changes or removes server state, against whatever base URL is set above.

post /experimental/worktree/reset # worktree.reset

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  directory: string
}

Responses

200 Success application/json

boolean

Example response from schema

false

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

worktree.reset

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

const client = createNikcliClient()
await client.worktree.reset({
  ...
})

Try it

directory query workspace query

Request body application/json

get /experimental/resource # experimental.resource.list

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Responses

200 McpResourceMap application/json

{
  [key: string]: McpResource
}

Example response from schema

{}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

experimental.resource.list

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

const client = createNikcliClient()
await client.experimental.resource.list({
  ...
})

Try it

directory query workspace query

get /experimental/managed-worktree # managed-worktree.list

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Responses

200 ManagedWorktreeList application/json

ManagedWorktreeInfo[]

Example response from schema

[
  {
    "id": "",
    "parentId": "",
    "name": "",
    "branch": "",
    "directory": "",
    "createdAt": 0
  }
]

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

managed-worktree.list

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

const client = createNikcliClient()
await client.managed-worktree.list({
  ...
})

Try it

directory query workspace query

post /experimental/managed-worktree # managed-worktree.create

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  from: string
  name?: string | null
  into?: string | null
}

Responses

200 ManagedWorktreeInfo application/json

{
  id: string
  parentId: string | null
  name: string
  branch: string
  directory: string
  createdAt: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}

Example response from schema

{
  "id": "",
  "parentId": "",
  "name": "",
  "branch": "",
  "directory": "",
  "createdAt": 0
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

managed-worktree.create

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

const client = createNikcliClient()
await client.managed-worktree.create({
  ...
})

Try it

directory query workspace query

Request body application/json

delete /experimental/managed-worktree # managed-worktree.remove

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  at: string
}

Responses

200 Success application/json

null

Example response from schema

null

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

managed-worktree.remove

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

const client = createNikcliClient()
await client.managed-worktree.remove({
  ...
})

Try it

directory query workspace query

Request body application/json

This changes or removes server state, against whatever base URL is set above.

post /experimental/managed-worktree/link # managed-worktree.link

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  at: string
  to?: string | null
}

Responses

200 ManagedWorktreeInfo application/json

{
  id: string
  parentId: string | null
  name: string
  branch: string
  directory: string
  createdAt: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}

Example response from schema

{
  "id": "",
  "parentId": "",
  "name": "",
  "branch": "",
  "directory": "",
  "createdAt": 0
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

managed-worktree.link

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

const client = createNikcliClient()
await client.managed-worktree.link({
  ...
})

Try it

directory query workspace query

Request body application/json

get /experimental/managed-worktree/children # managed-worktree.children

Parameters

Name	In	Type	Required
of	query	string	required
directory	query	string	optional
workspace	query	string	optional

Responses

200 ManagedWorktreeList application/json

ManagedWorktreeInfo[]

Example response from schema

[
  {
    "id": "",
    "parentId": "",
    "name": "",
    "branch": "",
    "directory": "",
    "createdAt": 0
  }
]

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

managed-worktree.children

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

const client = createNikcliClient()
await client.managed-worktree.children({
  ...
})

Try it

of query · required directory query workspace query

get /experimental/managed-worktree/ancestors # managed-worktree.ancestors

Parameters

Name	In	Type	Required
of	query	string	required
directory	query	string	optional
workspace	query	string	optional

Responses

200 ManagedWorktreeList application/json

ManagedWorktreeInfo[]

Example response from schema

[
  {
    "id": "",
    "parentId": "",
    "name": "",
    "branch": "",
    "directory": "",
    "createdAt": 0
  }
]

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

managed-worktree.ancestors

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

const client = createNikcliClient()
await client.managed-worktree.ancestors({
  ...
})

Try it

of query · required directory query workspace query

Schemas

The 14 schemas reachable from these endpoints. Each is shown one level deep; nested types link to their own entry below. Names ending in _2, _3 and so on are the OpenAPI emitter disambiguating same-named schemas declared by different HttpApi groups — they are distinct shapes, not duplicates.

ManagedWorktreeCreateInput

{
  from: string
  name?: string | null
  into?: string | null
}

ManagedWorktreeInfo

{
  id: string
  parentId: string | null
  name: string
  branch: string
  directory: string
  createdAt: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}

ManagedWorktreeLinkInput

{
  at: string
  to?: string | null
}

ManagedWorktreeList

ManagedWorktreeInfo[]

ManagedWorktreeRemoveInput

{
  at: string
}

McpResource

{
  name: string
  uri: string
  description?: string | null
  mimeType?: string | null
  client: string
}

McpResourceMap

{
  [key: string]: McpResource
}

ToolIDs

string[]

ToolList

ToolListItem[]

ToolListItem

{
  id: string
  description: string
  parameters: unknown
}

Worktree

{
  name: string
  branch?: string | null
  directory: string
}

WorktreeCreateInput

{
  name?: string | null
  branch?: string | null
  branchPrefix?: string | null
  baseBranch?: string | null
  remote?: string | null
  startCommand?: string | null
}

WorktreeDirectoryInput

{
  directory: string
}

WorktreeList

string[]