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

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.

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