npc:go

About 2132 wordsAbout 7 min

npc:go

Executes an AI task in a specified Docker image.

When an NPC role is mentioned in an Issue or PR comment, the built-in system/user prompts are used. For other events, you can customize the prompts via the systemPrompt, userPrompt, and role parameters.

You can install CLI tools and Skills required by the NPC at runtime in the image, such as CNB Skill. For more NPC configuration, see Custom NPC.

Applicable Events
Parameters
Environment Variables
Timeout
Output
Configuration Examples

Applicable Events

All Events

Parameters

Parameters at a Glance

The list below enumerates all npc:go parameters by purpose, so you can get an overview first and then jump to the relevant section for details.

role: NPC role name; only effective when API-triggered
systemPrompt: NPC system prompt; only effective when API-triggered
userPrompt: NPC user input; only effective when API-triggered
model: Model ID used by the agent; effective in all events
maxTurns: Max agent conversation turns; effective in all events
contextWindow: Model context window size; effective in all events
maxTokens: Max output token count; effective in all events
thinkingLevel: Model reasoning depth; effective in all events
supportImage: Whether to enable image input; effective in all events

role, systemPrompt, and userPrompt customize the NPC's prompts. Whether you need to configure them depends on how the build is triggered:

Comment-triggered (mentioning @NPC in an Issue/PR comment, i.e., the issue.comment@npc / pull_request.comment@npc events): the prompts are already provided by the NPC role, so no configuration is needed. The role and its prompts are defined in .cnb/settings.yml and take higher priority; role, systemPrompt, and userPrompt configured in this step are ignored.
API-triggered (api_trigger): you need to configure the prompts yourself. Setting npc.name=CodeBuddy in the request body only makes the build run with @CodeBuddy as the agent (affecting pipeline display, title, billing category, CNB_TOKEN permissions, etc.); the prompts still need to be provided by you:
- systemPrompt / userPrompt: pass them in this step's options;
- role (optional): if configured, it is resolved from NPC roles in .cnb/settings.yml and appended to the system prompt.

role

type: String
required: false

NPC role name. It must be defined in the roles field of the NPC section in the .cnb/settings.yml file. See UI Customization for reference. Takes effect only for API-triggered builds (api_trigger); ignored for comment-triggered builds (issue.comment@npc / pull_request.comment@npc).

systemPrompt

type: String
required: false

NPC system prompt. Required only for API-triggered builds (api_trigger); ignored for comment-triggered builds (issue.comment@npc / pull_request.comment@npc) since the prompts are provided by the NPC role.

userPrompt

type: String
required: false

NPC user input, mainly used for the user to describe tasks to the NPC. Required only for API-triggered builds (api_trigger); ignored for comment-triggered builds (issue.comment@npc / pull_request.comment@npc) since the prompts are provided by the NPC role.

maxTurns

type: Number
required: false

Maximum number of agent turns. Takes effect for all events. When the limit is reached the agent is aborted, and the output may be incomplete.

When omitted, the value follows these rules:

If no model is specified (platform default model is used), the maxTurns configured by the platform for the default model is used;
If a custom model is specified, the platform-configured value is not used, and the value falls back to the built-in default 500.

Explicitly passing a value always takes effect over the above.

model

type: String
required: false

Model id used by the agent. When omitted, the platform default model is used. Takes effect for all events.

contextWindow

type: String | Number
required: false

Model context window size. Accepts:

Lowercase-unit string: "128k" (k = 1000) or "1m" (m = 1000000)
Plain number: 128000 or "128000"

Allowed range is 128k ~ 1m (i.e. 128000 ~ 1000000 tokens); out-of-range or malformed values (uppercase, decimals, whitespace) are rejected. Used to trigger automatic summarization compaction when context exceeds the limit; should match the actual context window of the selected model. When omitted, the value follows these rules:

If no model is specified (platform default model is used), the value configured by the platform CodeBuddy NPC for the default model is used;
If a custom model is specified, the CodeBuddy NPC config is not inherited (context capacity varies by model and cannot be reused), and the value falls back to the built-in default 1m (1000000).

Explicitly passing a value always takes effect over the above. Takes effect for all events.

Example:

.cnb.yml
$:
  issue.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            contextWindow: 128k # equivalent to 128000, can also be written as "128000" or 128000

  # issue comment and PR comment events are configured identically; configure as needed
  pull_request.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            contextWindow: 128k # equivalent to 128000, can also be written as "128000" or 128000

maxTokens

type: String | Number
required: false

Model max output tokens. Accepts:

Lowercase-unit string: "48k" (k = 1000) or "1m" (m = 1000000)
Plain number: 64000 or "64000"

The accepted range is 200 ~ 1m (i.e. 200 ~ 1000000 tokens); out-of-range or malformed values (uppercase, decimals, whitespace) are rejected. Values in [200, 48000) are coerced up to 48000 (48k) when the request is sent. When omitted, the value follows these rules:

If no model is specified (platform default model is used), the value configured by the platform CodeBuddy NPC for the default model is used;
If a custom model is specified, the CodeBuddy NPC config is not inherited (capabilities vary by model and cannot be reused), and the value falls back to the built-in default 48k (48000).

Explicitly passing a value always takes effect over the above. Takes effect for all events.

Example:

.cnb.yml
$:
  issue.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            maxTokens: 64k # equivalent to 64000, can also be written as "64000" or 64000

  # issue comment and PR comment events are configured identically; configure as needed
  pull_request.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            maxTokens: 64k # equivalent to 64000, can also be written as "64000" or 64000

thinkingLevel

type: String
required: false

Model reasoning depth (thinking level). Valid values: off / minimal / low / medium / high / xhigh / max. When omitted, the value follows these rules:

If no model is specified (platform default model is used), the value configured by the platform CodeBuddy NPC for the default model is used;
If a custom model is specified, the CodeBuddy NPC config is not inherited (reasoning ability varies by model and cannot be reused), and the value falls back to the built-in default medium.

Explicitly passing a value always takes effect over the above. Takes effect for all events.

Example:

.cnb.yml
$:
  issue.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            thinkingLevel: high # increase reasoning depth for deeper thinking; values include off / low / medium / high / xhigh / max

  # issue comment and PR comment events are configured identically; configure as needed
  pull_request.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            thinkingLevel: high # increase reasoning depth for deeper thinking; values include off / low / medium / high / xhigh / max

supportImage

type: Boolean
required: false

Whether to enable the image input capability (multimodal). When enabled, the NPC can read and understand images pasted into Issue / PR comment scenarios and the like (supported formats: PNG / JPEG / WebP / GIF; a single image should not exceed 5 MiB).

When omitted, the value follows these rules:

If no model is specified (platform default model is used), the switch configured by the platform CodeBuddy NPC for the default model is used;
If a custom model is specified, the CodeBuddy NPC config is not inherited (image capability varies by model and cannot be reused), and the value falls back to the built-in default false (disabled).

Explicitly passing true registers the image-reading tool and declares image input; setting it to false or leaving it unset keeps images treated as plain text.

Example:

.cnb.yml
$:
  issue.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            supportImage: true # enable image input (multimodal)

  # issue comment and PR comment events are configured identically; configure as needed
  pull_request.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            supportImage: true # enable image input (multimodal)

Default Values of Model-Capability Parameters

model, maxTurns, contextWindow, maxTokens, thinkingLevel, and supportImage are all tied to the chosen model: different models do not share the same capabilities (context window, maximum output, reasoning depth, image input), so their defaults are not fixed.

No matter which parameter you configure, its value follows the same precedence rules:

If you explicitly specify the parameter, the value you pass wins.
If you do not specify it, the value depends on whether you specified model:
- No model specified (using the platform default model): the platform's CodeBuddy NPC configuration for the default model is inherited.
- A custom model is specified: the default model's configuration is not inherited, and the parameter falls back to the built-in default in the list below.

maxTurns: 500
contextWindow: 1m (1000000)
maxTokens: 48k (48000)
thinkingLevel: medium
supportImage: false (disabled)

For each parameter, the exact value inherited from the default model when model is not specified is documented in that parameter's own section.

Environment Variables

npc:go reads all environment variables of the current pipeline, including the platform's built-in variables, the env and imports at the pipeline / stage / job levels, and exports from upstream jobs.

Timeout

The timeout declared on the job applies to each tool execution (e.g., bash commands) of the agent: a single tool execution is forcibly interrupted and returns a failure to the agent once it exceeds the configured duration or produces no output for that duration; if not declared, the default values apply (10-minute no-output timeout, 2-hour maximum per execution).

The agent session itself has no overall timeout; its total duration is bound by the pipeline timeout (20 hours).

Configuration Examples

1. NPC event pipeline: Invoke npc:go on the issue.comment@npc event. The image must include the CLI tools and Skills required by the NPC runtime (see step 2 below for building the image):

.cnb.yml
$:
  issue.comment@npc:
    - docker:
        # Specify image containing CLI tools and Skills required by the NPC
        image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
      stages:
        - name: npc go
          type: npc:go

2. Build and push the NPC image: Push the image to the artifact registry so it can be used by the NPC event pipeline above:

.cnb.yml
main:
  push:
    - services:
        - docker
      stages:
        - name: Docker build
          script: docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest .
        - name: Docker push
          script: docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest

Install the Skills and CLI tools required by the NPC in the Dockerfile. The following example installs cnb-skill and cnb-cli.

Dockerfile
FROM node:22-bookworm-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates git git-lfs curl jq ripgrep \
    && rm -rf /var/lib/apt/lists/* \
    && git lfs install \
    && npm install -g @cnbcool/cnb-cli skills \
    && npx skills add https://cnb.cool/cnb/skills/cnb-skill.git -g -y

Skills are automatically loaded from the following directories: ~/.agents/skills, ~/.codebuddy/skills and their project-level counterparts: .agents/skills, .codebuddy/skills.

Project-level Skills take priority over user-level Skills. A project-level Skill with the same name will override its user-level counterpart.

The NPC role prompt is defined in the .cnb/settings.yml file. See Custom NPC for details.