npc:go

Executes an AI task in a pipeline; it is the runtime entry point for NPC.

Use cases: use it when you want AI to take part in an automated flow - for example, mentioning @NPC in an Issue/PR comment so it answers questions or helps change code, or triggering it from other events or api_trigger so AI handles build artifacts, generates reports, and so on. Such tasks usually require installing CLIs and Skills and connecting to a model, which is costly to script by hand; npc:go folds this into a single built-in task.

The NPC runs in a specified Docker image, so you can install the CLI tools and Skills it needs there, such as CNB Skill.

Where prompts come from: for @NPC comment triggers the platform automatically starts a pipeline that uses npc:go, and the prompts come with the NPC role, so no configuration is needed. For other triggers you must define the prompts yourself; see Parameters. For more NPC configuration, see Custom NPC.

• Applicable Events
• Parameters
  • Prompt Configuration
• 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 you provide the prompts
• systemPrompt: NPC system prompt; optional when you provide the prompts, defaults to the built-in api_trigger prompt
• userPrompt: NPC user input; required when you provide the prompts
• 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

Prompt Configuration

role, systemPrompt, and userPrompt all relate to prompts, but whether you need to configure them depends on two independent dimensions; just judge each one separately.

Dimension 1: how the NPC semantics is triggered

• @NPC comment trigger (issue.comment@npc / pull_request.comment@npc): the entry point is @NPC in a comment, and the platform starts the pipeline automatically.
• Other triggers: event triggers such as push / crontab, manual triggers, and api_trigger with npc.name=CodeBuddy in the request body (which makes the build run as an NPC).

Dimension 2: who provides the prompts

• Provided by the NPC role: for @NPC comment triggers, the platform injects the prompts defined by the role in .cnb/settings.yml, so no configuration is needed; the three parameters above are ignored even if set (role definitions take higher priority).
• Provided by you: in all other cases you must pass the prompts in options:
  • systemPrompt (optional): the system prompt; when omitted, the built-in api_trigger system prompt is used;
  • userPrompt (required): the user input;
  • role (optional): resolved from NPC roles in .cnb/settings.yml and appended to the system prompt.

How the two dimensions relate: only @NPC comment triggers come with prompts from the role; every other trigger (including api_trigger with npc.name) requires you to provide them. npc.name in api_trigger only decides which agent identity the build runs as (affecting pipeline display, title, billing category, CNB_TOKEN permissions, etc.); it does not provide prompts.

role alone cannot replace the prompts

role only appends the role prompt as a personality block; it provides neither the system prompt nor the user input. systemPrompt may be omitted (the built-in api_trigger system prompt is then used), but a missing or empty userPrompt is still rejected, as is configuring only role:

.cnb.yml

$:
  # A crontab trigger requires you to provide the prompts
  crontab:
    - cron: "0 10 * * *"
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            role: Release Guard
            # userPrompt still cannot be omitted; systemPrompt is optional and falls back to the built-in prompt
            systemPrompt: You are the release guard, responsible for checking and updating version numbers in the repository.
            userPrompt: Check and update the repository version numbers.

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 when you provide the prompts; for @NPC comment triggers (issue.comment@npc / pull_request.comment@npc) the prompts come with the NPC role, so this parameter is ignored.

systemPrompt

• type: String
• required: false

NPC system prompt, defining the NPC's behavior guidelines and task boundaries.

Optional when you provide the prompts, including event triggers such as push / crontab, manual triggers, and api_trigger with npc.name; ignored for @NPC comment triggers since the prompts are provided by the NPC role in .cnb/settings.yml.

When omitted, the built-in api_trigger system prompt is used (NPC baseline guidelines plus tool-usage conventions), and Skills, knowledge bases, the role personality block and project context are still appended. This suits cases where the task is already fully described in userPrompt and no extra behavior constraints are needed.

When role is configured you do not need to pass systemPrompt either: the resolved role prompt is appended as a personality block on top of the built-in prompt.

userPrompt

• type: String
• required: false

NPC user input, mainly used for the user to describe tasks to the NPC.

Required when you provide the prompts (a missing or empty value is rejected); ignored for @NPC comment triggers 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).

Image size is handled automatically: before reading, the NPC compresses the image to 512 KiB or less using ffmpeg inside the container (downscale plus JPEG conversion; ffmpeg ships with the default image, so no extra installation is needed). The compressed copy is inlined as base64 for the model, and the original file is left untouched. Only when the compressed image still exceeds the 1 MiB inline limit does the read fail with downscaling guidance.

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:

1. If you explicitly specify the parameter, the value you pass wins.
2. 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

Tool execution timeout

The agent runs many tools (e.g., bash commands) during a session. The timeout declared on the job applies to each tool execution rather than the entire agent session:

• 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 timeout is not declared, the default values apply: 10-minute no-output timeout and a 2-hour maximum per tool execution.

In other words, timeout bounds a single tool execution, and a session may run many tool executions, each limited on its own.

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.

Global-level Skills take priority over project-level Skills. A global-level Skill with the same name will override its project-level counterpart, so a stale copy checked into the repo cannot shadow the version shipped in the image.

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