Prewarm Process Usage Guide ​

Applicable to: @tencent-ai/codebuddy-code (cbc / codebuddy)

The prewarm process lets cbc complete cold startup and suspend (load bundle → container initialization → authentication → product configuration → MCP discovery), so that when awakened via local IPC it only needs to bind a working directory and can immediately serve. This is ideal for scenarios requiring "sub-second session startup" (e.g., serve/acp gateways, session pools, scheduler pre-launch).

Benefit: Local benchmarks show single-session startup wait reduced from approximately 3.7s to ~1ms.

Disabled by default. Only enabled when --prewarm is explicitly passed; does not affect any existing usage.

Quick Start ​

1. Start a Prewarmed Process (Standby) ​

bash
cbc --prewarm --prewarm-id pool1

The process will complete cold startup, then suspend at a local IPC endpoint in standby (without binding a working directory):

  • macOS / Linux: unix socket /tmp/codebuddy-prewarm-pool1.sock (permission 0600, current user only)
  • Windows: named pipe \\.\pipe\codebuddy-prewarm-pool1

--prewarm-id can be omitted; defaults to using the process PID as the identifier.

2. List / Activate (Lightweight Management Command cbc-prewarm) ​

cbc-prewarm is a pure Node zero-dependency lightweight command that does not load the main program bundle and returns in milliseconds.

bash
# List prewarmed processes discovered on the current machine
cbc-prewarm list

# Health check
cbc-prewarm ping pool1

# Query status (idle / activating / active)
cbc-prewarm status pool1

# Activate: bind to target working directory and start serving
cbc-prewarm activate pool1 --cwd /path/to/project -- --serve

Arguments after -- in activate are passed through to the awakened process (equivalent to normal cbc <args>). After activation, the process chdirs to --cwd, enters the corresponding mode based on the passed-through arguments (e.g., --serve / --acp), and proactively closes the IPC socket (one-time activation; afterwards it communicates through its own service port).

--cwd is optional: When omitted, the prewarmed process retains the working directory from cold startup (no chdir, no cwd change broadcast). This is suitable for callers that don't need to switch directories and just want to reuse the prewarmed container. Only pass --cwd when you need to bind to a specific project directory.

Mode is unrestricted: The passed-through arguments can be any normal cbc arguments. Persistent modes like --serve, --acp, etc. all take effect as-is — the prewarmed process has no restrictions or rewrites on modes. Pass --serve / --acp for persistent services; without a persistent mode flag, it takes the one-shot command path, exiting after execution (headless with no TTY).

External Program Integration (IPC Protocol) ​

To activate a prewarmed process from your own program, connect to the local socket / pipe and send one line of JSON (NDJSON, one message per line), then read one line of JSON response.

Address Convention ​

macOS/Linux : /tmp/codebuddy-prewarm-<id>.sock
Windows     : \\.\pipe\codebuddy-prewarm-<id>

Messages ​

jsonc
// Health check
{ "cmd": "ping" }
// → { "ok": true, "cmd": "ping", "status": "idle", "pid": 12345 }

// Query status
{ "cmd": "status" }
// → { "ok": true, "status": "idle"|"activating"|"active", "cwd": "...", "endpoint": "..." }

// Activate (cwd is optional — omit to retain cold-start cwd; args are passed through to cbc)
{ "cmd": "activate", "cwd": "/path/to/project", "args": ["--serve"], "sessionId": "optional" }
// → { "ok": true, "cmd": "activate", "status": "activating", "cwd": "..." }

activate can only succeed once; repeated activations return { ok: false, error: "already activated" }.

Node.js Example ​

js
const net = require('net');

function prewarmAddr(id) {
  return process.platform === 'win32'
    ? `\\\\.\\pipe\\codebuddy-prewarm-${id}`
    : `/tmp/codebuddy-prewarm-${id}.sock`;
}

function activate(id, { cwd, args = [] }) {
  return new Promise((resolve, reject) => {
    const sock = net.connect(prewarmAddr(id), () => {
      sock.write(JSON.stringify({ cmd: 'activate', cwd, args }) + '\n');
    });
    let buf = '';
    sock.on('data', d => {
      buf += d;
      const nl = buf.indexOf('\n');
      if (nl >= 0) { sock.end(); resolve(JSON.parse(buf.slice(0, nl))); }
    });
    sock.on('error', reject);
  });
}

// Activate pool1, bind to target directory and start in serve mode
const res = await activate('pool1', { cwd: '/Users/me/project-A', args: ['--serve'] });
console.log(res); // { ok: true, cmd: 'activate', status: 'activating', cwd: '...' }

Behavior and Constraints ​

  • One process, one session: Each prewarmed process binds to a working directory only once in its lifetime (at the moment of activation), then is discarded. To serve multiple directories, prewarm multiple processes (with different --prewarm-id values), each independent and non-interfering.
  • Working directory isolation: After activation, the process chdirs and broadcasts a cwd change. File watchers automatically rebind, and project-level caches (settings / memory / skills / plugins / product configuration) are automatically invalidated and rescanned, ensuring no stale configuration from the temporary prewarm directory is read.
  • USER-level configuration sharing: User-level settings / authentication / MCP under ~/.codebuddy/ are naturally shared across all prewarmed processes.
  • Security: Unix socket permissions are tightened to 0600 (owner only), preventing other users on the same machine from connecting and hijacking.
  • Exit cleanup: Graceful exit (SIGINT/SIGTERM) or completion of activation automatically cleans up the socket; sockets left behind by SIGKILL are automatically overwritten on the next startup with the same id.

Configuration ​

Prewarm-related parameters can only be configured via CLI flags: --prewarm / --prewarm-id <id> / --prewarm-force.