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; optional when API-triggered, defaults to the built-in api_trigger prompt
• userPrompt: NPC user input; required 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

Prompt Configuration

role, systemPrompt, and userPrompt all relate to prompts. Whether you need to configure them depends on how the build is triggered:

• Comment-triggered (issue.comment@npc / pull_request.comment@npc): the entry point is @NPC in a comment, and the platform starts the pipeline automatically and injects the prompts defined by the role in .cnb/settings.yml. No configuration is needed; the parameters above are ignored even if set (role definitions take higher priority).
• API-triggered (api_trigger, as well as push / crontab / manual triggers): you must provide the prompts yourself through options:
  • systemPrompt (optional): the system prompt; when omitted, the built-in api_trigger system prompt is used;
  • userPrompt (required): the user input; a missing or empty value is rejected;
  • role (optional): resolved from NPC roles in .cnb/settings.yml and appended to the system prompt as a personality block.

npc.name=CodeBuddy in the api_trigger request body 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 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, defining the NPC's behavior guidelines and task boundaries.

Effective and optional 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.

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 for API-triggered builds (api_trigger); a missing or empty value is rejected. 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:

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

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.

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.