Daemon Mode and Background Sessions

Daemon mode runs CodeBuddy Code as a background resident service, independent of any terminal window. Once started, it provides a full HTTP API and Web UI, ready to accept requests at any time.

Core value: Transform the CLI from "use and go" to "always on standby".

Concepts

Concept	Description
Worker	A running CLI process, registered via a PID file in ~/.codebuddy/sessions/
Daemon	A background resident HTTP service process (--serve mode), managed via daemon start
Background Session (bg)	A non-interactive task started with --bg, with output automatically logged to a file

Daemon Management

Starting the Daemon

# Start the daemon (runs in background, auto-assigns port)
codebuddy daemon start

# Specify a port
codebuddy daemon start --port 8080

# Specify bind address (allow remote access)
codebuddy daemon start --host 0.0.0.0

# Specify permission mode (defaults to delegate mode)
codebuddy daemon start --permission-mode default

# Pass other standard parameters (model, mcp-config, etc. are automatically inherited)
codebuddy daemon start --model claude-sonnet-4-20250514 --mcp-config ./mcp.json

Once started, the daemon runs as a detached process and the parent process exits immediately. Local addresses have password-free access by default; non-local addresses automatically enable password authentication.

Default delegate mode: The daemon runs in delegate mode by default—the main agent only handles coordination and scheduling, without directly modifying code. All implementation work is done through subagents. You can switch to other modes via --permission-mode.

Parameter inheritance: Standard CLI parameters specified with daemon start (--model, --permission-mode, --mcp-config, --tools, --agent, --settings, etc.) are automatically inherited by daemon child processes.

Idempotent startup: Running daemon start multiple times does not create multiple daemons. If a daemon is already running, it returns the existing daemon's information.

Checking Status

codebuddy daemon status
# {"status":"running","pid":12345,"endpoint":"http://127.0.0.1:51862","startedAt":1775498920401}

Stopping / Restarting

codebuddy daemon stop
codebuddy daemon restart

Background Sessions

Starting Background Tasks

# Execute a task in the background
codebuddy --bg "implement login page"

# Specify a name (easier to find)
codebuddy --bg --name feature-login "implement login page"

Background sessions run in --print -y mode (no TUI + skip permission confirmations), with stdout/stderr redirected to ~/.codebuddy/logs/{name}.log.

Process Management Commands

# List all active Workers
codebuddy ps

# View background session logs
codebuddy logs feature-login

# Follow logs continuously (similar to tail -f)
codebuddy logs feature-login -f

# Attach to a background session
codebuddy attach feature-login

# Kill a background session
codebuddy kill feature-login

HTTP API

All Worker and Daemon management capabilities are exposed via REST APIs. The Web UI Workers page is built on top of these APIs.

See the Workers & Daemon section in the HTTP API documentation for details.

Examples

# List all Workers
curl http://127.0.0.1:8080/api/v1/workers

# Start a Daemon
curl -X POST http://127.0.0.1:8080/api/v1/daemon/start \
  -H "Content-Type: application/json" \
  -d '{"port": 9090}'

# View Worker logs (telemetry logs)
curl "http://127.0.0.1:8080/api/v1/workers/12345/logs?type=telemetry&tail=100"

# Kill a Worker
curl -X DELETE http://127.0.0.1:8080/api/v1/workers/12345

Web UI

After starting in --serve mode, the Web UI provides three management pages:

• Workers — Worker process management and Daemon control
• Logs — Standalone log viewer with Worker selection, log type switching, and keyword search
• Metrics — System resource monitoring and per-Worker process-level metrics

Log System

The log API supports 4 types, with automatic priority-based selection:

Type	Path	Content	Trigger
telemetry	~/.codebuddy/logs/{date}/{workspace}.log	Info/Warn/Error from all modules	Always (default priority)
process	~/.codebuddy/logs/{name}.log	Process stdout/stderr	bg/daemon only
debug	~/.codebuddy/debug/{sessionId}.txt	Detailed debug information	Requires --debug
transcript	~/.codebuddy/projects/{id}/{sessionId}.jsonl	Conversation history	Always

PID File Registry

Each CLI process registers a PID file in ~/.codebuddy/sessions/ on startup:

~/.codebuddy/sessions/
├── 12345.json          # Local process (PID as filename)
├── 67890.json          # Another local process
└── manual-abc123.json  # Manually added remote Worker

PID file contents:

{
  "pid": 12345,
  "sessionId": "interactive-12345",
  "cwd": "/home/user/project",
  "startedAt": 1775498920401,
  "kind": "interactive",
  "url": "http://127.0.0.1:8080",
  "mode": "local",
  "version": "2.78.1",
  "hostname": "my-machine"
}

Process liveness is detected via kill -0. Manually added remote Workers are detected via heartbeat timeout (2 minutes).

Environment Variables

Variable	Description
CODEBUDDY_SESSION_KIND	Worker type (interactive / bg / daemon)
CODEBUDDY_SESSION_NAME	Background session display name
CODEBUDDY_SESSION_LOG	Background session log path
CODEBUDDY_GATEWAY_AUTH	Authentication mode (none / password)

Use Cases

Persistent Development Server

Start a daemon once during daily development, then interact with the AI anytime through the browser or API without opening a terminal each time.

codebuddy daemon start --port 8080
# Open http://127.0.0.1:8080 in your browser
# The service keeps running after closing the terminal

CI/CD Automation Backend

Start a daemon in a CI pipeline as an Agent service, and have other steps call it via HTTP API for code reviews, test generation, and other tasks.

# CI startup
codebuddy daemon start --port 9090

# Other CI steps call the API
curl -X POST http://127.0.0.1:9090/api/v1/runs \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Review the code changes in this PR"}'

Shared Agent for Teams

Start a daemon on a development machine bound to a LAN address, allowing team members to share the same Agent environment through the Web UI.

codebuddy daemon start --host 0.0.0.0 --port 8080
# Colleagues access http://192.168.1.100:8080

Batch Background Tasks

Use --bg to start multiple background sessions for different tasks simultaneously, and manage them with ps/logs/kill.

codebuddy --bg --name "refactor-auth" "refactor the auth module"
codebuddy --bg --name "add-tests" "add unit tests for the utils directory"
codebuddy --bg --name "fix-types" "fix all TypeScript type errors"

# Check progress
codebuddy ps
codebuddy logs refactor-auth

WeChat/WeCom Bot Backend

Run the daemon as a persistent backend service for a chatbot, receiving messages through long-lived connections.

codebuddy daemon start
# Connect to WeChat/WeCom channels via the remote control feature

IDE Extension Backend

IDE plugins connect to the daemon via the ACP protocol, providing AI-assisted programming without restarting the CLI process each time the IDE is opened.

Difference from --serve

Feature	--serve	daemon start
Lifecycle	Tied to terminal, exits when terminal closes	Background resident, independent of terminal
Startup	Runs in foreground	Forks a detached child process
Management	Stop with Ctrl+C	daemon stop/status/restart
Multiple starts	Creates a new process each time	Idempotent, maintains only one daemon
Typical use	Temporary development/debugging	Long-running service