# Runtime architecture

> Modern 0.4.0 is the stable default. Install v0.4.0 for the release or follow modern for development. Requires Pi 0.99.2 or newer.

Web page: https://igorwarzocha.github.io/pi-clawa/modern/docs/reference/runtime/

The package entrypoint is `src/index.ts`. Pi imports it as an extension factory. The factory creates
one Clawas runtime, Pulse runtime, hydration state, memory job queue, and comms server, then
registers hooks, commands, tools, renderers, and main-only controls.

## Session start

Activation comes first. A global install stays dormant in directories without `.pi/claw.jsonc`.
Dormant sessions receive no Clawa tools, skills, prompt changes, or running home services. A
configured home activates globally; a project install or explicit `pi -e` also requests automatic
bootstrap.

In an active session, startup, reload, new session, resume, or fork:

1. creates or reads `.pi/claw.jsonc`;
2. performs protective bootstrap when needed;
3. resolves defaults and synchronizes the process environment;
4. names worker sessions when running in worker role;
5. opens the transcript-free comms listener so launchers can deliver the first task;
6. migrates an existing `vault/` into shared `memory/` and imports legacy SQLite rows without deleting the database;
7. prepares living-home hydration for the next agent turn.

First run creates files without starting an autonomous agent turn. Onboarding joins the first human
message or task through `before_agent_start`. A concrete task takes priority over introductions,
so optional context binding can finish before any work begins. Clawas control and the Pulse timer
attach when the first task starts, or when a home command needs them.

`session_shutdown` drains the current comms alias maintenance and Pulse work. Worker tabs remain
open after main quits or reloads.

## Prompt shaping

Before an agent starts, Clawa filters Pi context files to the resolved home and adds the configured
main or worker identity as the native `clawa_identity` section. Living documents use `clawa_home`.
Pi's tool context and other extensions' prompt ownership remain intact, including Codex.

Idle mail, reports, and main Pulses share a coalesced native user kickoff so this preparation also
runs before autonomous work. Reports and Pulses retain their custom-message metadata; during active
work, reports steer and Pulses follow up as before. Readiness failures are reported before dispatch.
Pi's extension send API does not return asynchronous startup errors, so a missing start acknowledgement
is reported as uncertain rather than retried. A later native start clears that fence.

Clawa does not delete custom prompts or opaque full-prompt overrides. An opaque override can hide
home sections and bypass context-file scoping; Clawa warns in the UI when it sees one at its hook.
Use `.pi/APPEND_SYSTEM.md` or structured prompt sections for additions that compose with the home.
This is home-scoping behavior, not a sandbox against other extensions.

## Continuity context

At `before_agent_start`, Clawa reads the bounded living documents into Pi's native structured
prompt. Text refreshes for every turn, including after Pi compaction or optional Pi Codex continuity.
There is no parallel provider rewrite or family-context routing layer.

An optional visual self-card uses a native, deduplicated message on the first turn or after Pi
compaction. It is not repeated on every turn. After external context rollover, a path reminder lets
the Clawa view the image explicitly when needed.

Nested `AGENTS.md` context remains separate. It arrives progressively through relevant read and
discovery tool results as work reaches governed paths.

## Compaction and memory consolidation

Plain Pi owns compaction and overflow recovery. Optional Pi Codex owns its configured continuity.
Clawa has no rollover engine, MemoryPass threshold, or compaction settings. It provides
`clawa_memory` for house Markdown and retained chat notes, and `clawa_history` for house archives
and committed memory revisions. Generic continuity tools belong to the extension that provides
them, not Clawa.

`/memory remember` freezes the current conversation, starts a fresh one, and queues optional idle
consolidation in a private Pi session without live extensions. That session has only a bounded
memory-file tool for shared memory and the five living-document owners, not shell, network, bot, or
Git tools. It leaves changes uncommitted. Queued jobs survive restart; interrupted work requeues,
while ordinary failures stay visible for explicit retry.

## Main and worker roles

`PI_CLAWAS_ROLE=worker` fixes the worker role at module load. Workers receive house memory and history,
hydration, prompt shaping, comms, and private reporting, but not the main monitor,
`/steer`, `/jump`, or Pulse GUI.

Workers are ordinary Pi sessions, each in a named Herdr tab or tmux window. The main runtime opens or
adopts these tabs; `.pi/clawas/session-registry.json` keeps both session history and terminal location.
Closing a tab stops its worker until a message or `/jump` reopens it. Local newline-delimited socket messaging
carries private coordination without using Pi subprocess RPC or placing messages on a public adapter.

Launches forward standard Pi provider, proxy, certificate, and launch environment settings, plus
environment references declared in `models.json` and registered provider configurations. The new host
owns terminal/session identity. The launcher neither resolves credentials nor runs provider commands;
it omits credential-bearing command output from launch errors.

Clawa owns resident launch and communication without Shepherdr. With optional Codex sharing enabled,
fresh resident sessions bind through Codex's public API over the existing Clawa sockets before any
startup prompt or task. Existing sessions are never rebound. Session shutdown fences pending
bindings before waiting for worker connections to drain. Its optional CodeMode adapter exposes
house and message tools without requiring Codex for ordinary Pi use.