Building an Agent Daemon

An agent daemon is the missing layer between a terminal coding assistant and a collaborative product: it owns the local process, translates runtime-specific events, injects tools, and gives the agent a durable identity.

A CLI agent is designed for one human sitting at one terminal. That is the wrong boundary for a product like Zouk, where agents are colleagues: they receive messages while asleep, claim tasks, reply in threads, survive browser reloads, and carry memory across days. The daemon is not a smarter prompt. It is the operating boundary around the agent.

The shape below comes from building Zouk Daemon against several real runtimes: Claude Code stream-json, Codex app-server JSON-RPC, Hermes/Coco/OpenCode over ACP, plus custom HTTP-backed agents. The details differ, but the construction sequence stays stable.

Start With Process Ownership

The first job is boring and decisive: the daemon, not the web app and not the terminal, must own the child process. It chooses the working directory, environment, model, system prompt, MCP configuration, and resume token. It also decides when the process is allowed to die.

 1export interface Driver { 2  id: string; 3  supportsStdinNotification: boolean; 4  busyDeliveryMode: "notification" | "direct" | "none"; 5  6  spawn(ctx: SpawnContext): { process: ChildProcess }; 7  parseLine(line: string): ParsedEvent[]; 8  encodeStdinMessage(text: string, sessionId: string | null): string | null; 9  buildSystemPrompt(config: AgentConfig, agentId: string): string;10}

That small interface is the useful abstraction. Everything runtime-specific stays inside the driver: Claude gets `--output-format stream-json`, Codex gets `thread/create` or `thread/resume`, Hermes gets `session/new` or `session/load`, and a custom service may just stream HTTP events. The rest of the daemon sees one process and one event stream.

Sessions Are Not Processes

A process is disposable. A session is the agent runtime’s conversation state. Good daemon behavior comes from keeping that distinction clear: kill the process on idle, keep the session id for persistent agents, clear it for ephemeral agents, and treat reset as “stop plus start without the old session.”

 1async function stopProcess(child) { 2  if (!child || child.exitCode !== null) return; 3  child.kill("SIGTERM"); 4  await waitForExit(child, 5000).catch(() => child.kill("SIGKILL")); 5} 6  7function cacheIdleAgent(agent) { 8  return { 9    config: { ...agent.config, sessionId: agent.sessionId },10    workingDirectory: agent.workingDirectory,11    lastActivity: agent.lastActivity,12  };13}

This is where many daemons become flaky. A new message can arrive while the previous idle process is still shutting down. A runtime may report a successful resume without echoing the session id. Some runtimes can accept a steering message mid-turn; others need a queue until `turn_end`. These are lifecycle rules, not UI rules, so they belong in the daemon.

 1const pendingStop = agentsStopping.get(agentId); 2if (pendingStop) await pendingStop; 3  4if (agents.has(agentId)) { 5  await stopAgent(agentId, { wait: true }); 6} 7  8agentsStarting.set(agentId, startAgentProcess(agentId, config));

That guard looks small, but it prevents a subtle class of bugs: two processes believing they own the same agent slot, same workspace, and same session. A daemon is mostly a set of these small invariants.

Put The Network Boundary Above The Daemon

The product needs network access. The agent needs local access. Mixing those two facts is how you end up with browser tabs owning local shells, or servers trying to run commands on the wrong machine. Keep the server as a relay and the daemon as the local authority.

 1{ "type": "agent:start", "agentId": "agent-louise", "config": { "runtime": "codex" } } 2{ "type": "agent:deliver", "agentId": "agent-louise", "message": "Fix task #82" } 3{ "type": "agent:activity", "agentId": "agent-louise", "activity": "Reading files..." } 4{ "type": "agent:status", "agentId": "agent-louise", "status": "idle" }

Reconnect Should Be Boring

The daemon connects outward to the server, so it should assume the socket will drop. On reconnect it can re-announce detected runtimes, capabilities, running sessions, idle-cached sessions, and the last known activity for each agent. That makes a browser reload or network hiccup a reconciliation problem, not an agent restart.

Normalize The Runtime Stream

Every useful runtime emits a different stream. Claude sends `system`, `assistant`, and `result` records. Codex uses thread events with item updates. ACP runtimes send JSON-RPC updates like `session/update`, `tool_call`, and `usage_update`. If those shapes leak upward, every product feature becomes runtime-specific.

 1type ParsedEvent = 2  | { kind: "session_init"; sessionId: string } 3  | { kind: "thinking"; text: string } 4  | { kind: "text"; text: string } 5  | { kind: "tool_call"; name: string; input?: unknown } 6  | { kind: "context_usage"; contextUsage: ContextUsageSnapshot } 7  | { kind: "turn_end" } 8  | { kind: "error"; message: string };

The important part is not the names. It is that the product has one vocabulary for “the agent is thinking,” “the agent is calling a tool,” “the context window is filling,” and “the turn is finished.” That is what makes model switching and runtime switching product features instead of rewrites.

Activity Is Part Of The UX

A daemon that only forwards final text makes the agent feel frozen. Surface tool starts, command summaries, file edits, message sends, and context usage as first-class activity. Send heartbeats while a long turn is running so the server can reconcile stale UI state after reconnects.

Give The Agent Product Tools

Once the process and event stream are stable, the next boundary is the tool plane. In a collaborative system, the agent must not use shell commands or private HTTP calls to participate in the product. It should call the same explicit tools a human-facing client would expose: check messages, read history, claim tasks, send replies, upload files.

 1{ 2  "name": "chat", 3  "command": "node", 4  "args": [ 5    "dist/chat-bridge.js", 6    "--agent-id", "agent-louise", 7    "--server-url", "https://zouk.example", 8    "--auth-token", "daemon-scoped-token" 9  ]10}

Different runtimes accept that MCP bridge differently. Claude, Gemini, Copilot, and Kimi can read a generated MCP config file. ACP runtimes such as Hermes and OpenCode can receive `mcpServers` in `session/new` or `session/load`. The daemon owns those differences so the agent receives the same tools either way.

Multi-agent Is Scheduling, Not Telepathy

Two agents do not need to secretly talk to each other. They need shared state and a scheduler. A task board, a thread, a game board, or a queue can decide whose turn it is. The daemon then wakes the right local process and delivers a normal message: “your turn,” “review this,” “continue after task #82.”

Let the product own coordination. Let the daemon own the local process. Let tools be the only way the agent changes shared state.

Connect The Daemon To OpenViking

The last step is memory and context. A daemon already knows the agent identity, workspace, runtime, and task flow. That makes it the natural place to attach OpenViking: resolve credentials once, pass them to the child process, and expose memory browsing or retrieval as a capability.

Keep the roles separate. The daemon owns lifecycle, transport, protocol normalization, scheduling, and tool injection. OpenViking owns durable context: memories, resources, sessions, archive summaries, retrieval, and its own `/mcp` tools.

The OpenViking docs now frame this as an integration-depth choice: generic MCP clients call OpenViking on demand; hooks-based plugins drive recall and capture from lifecycle events; SDK integrations wire retrieval and storage into framework-native abstractions. A daemon sits closest to the hooks-based path because it already sees start, prompt, turn end, compaction, idle, and session end. Agent Integrations Overview

For an agent daemon, the practical answer is usually both: use lifecycle integration for the things that must always happen, and also register OpenViking’s `/mcp` endpoint so the model can make explicit context decisions when it needs to inspect or store something.

 1const openviking = { 2  baseUrl: process.env.OPENVIKING_URL 3    ?? process.env.OPENVIKING_BASE_URL 4    ?? "http://127.0.0.1:1933", 5  apiKey: process.env.OPENVIKING_API_KEY 6    ?? process.env.OPENVIKING_BEARER_TOKEN 7    ?? "", 8  accountId: process.env.OPENVIKING_ACCOUNT ?? "", 9  userId: process.env.OPENVIKING_USER ?? "",10  agentId: process.env.OPENVIKING_AGENT_ID ?? "agent-runtime",11  timeoutMs: 15000,12  recallLimit: 6,13  recallTokenBudget: 2000,14};

 1OPENVIKING_URL=https://ov.example 2OPENVIKING_API_KEY=ov_user_key 3OPENVIKING_ACCOUNT=default 4OPENVIKING_USER=zayn 5OPENVIKING_AGENT_ID=louise 6OPENVIKING_CLI_CONFIG_FILE=/agent-data/louise/openviking/ovcli.conf

In Zouk Daemon, daemon-wide OpenViking config can come from environment variables, `~/.openviking/ovcli.conf`, or `~/.openviking/ov.conf`. Server-provisioned per-agent credentials can override that. The daemon then writes a per-agent `ovcli.conf` and points `OPENVIKING_CLI_CONFIG_FILE` at it, so env-based clients and file-based clients see the same identity.

This is the point where the daemon stops being just a launcher. It becomes the agent’s durable host. The same identity that receives a Zouk task can read `viking://user/louise/memories`, write new observations, and re-enter the next turn with context that did not have to fit in the previous prompt.

 1{ "type": "agent:memory:list", "agentId": "agent-louise", "uri": "/" } 2{ "type": "agent:memory:read", "agentId": "agent-louise", "uri": "viking://user/louise/memories/project-notes" } 3{ "type": "agent:memory:content", "agentId": "agent-louise", "content": "..." }

The Operational Loop

1. Start or point at an OpenViking server and verify `GET /health`.
2. Load daemon-level or per-agent config, then pass the resolved identity to the spawned runtime.
3. Before a user turn, retrieve bounded memories or resources and inject only the useful context block.
4. After a turn, append sanitized user and assistant messages into a persistent OpenViking session.
5. On compaction or session end, commit the session so archive and memory extraction can run.
6. Register `${OPENVIKING_URL}/mcp` with the same auth so the model can explicitly search, read, store, and add resources.

The Checklist

A production agent daemon does not need to be large. It does need the right invariants. If you can answer these questions, the architecture is probably sound.

1. Can the daemon kill an idle process without losing the persistent session?
2. Can a reset start a truly fresh runtime instead of accidentally resuming old state?
3. Can the server render activity without understanding runtime-specific event formats?
4. Can messages arriving mid-turn be queued or steered according to that runtime’s capabilities?
5. Can the agent change shared product state only through explicit tools?
6. Can OpenViking identify the account, user, and agent behind every memory operation?

That is the build order: own the process, put a network control plane above it, normalize runtime streams, inject product tools, and attach durable context. Once those boundaries exist, “multi-agent” is no longer magic. It is a scheduler waking named daemons that can work, report activity, use tools, and remember.