Principles Disciple

Stop correcting the same AI behavior across sessions.

Principles Disciple (PD) is a native OpenClaw plugin that captures the moments where you correct your agent, turns repeated corrections into reviewable principle proposals, and — only after you approve them — lets those principles influence how the agent behaves in future sessions.

Owner-controlled · Observable · Reversible

The problem

Every session starts from zero. You correct the agent — "confirm scope before cross-module edits", "don't touch generated files", "ask before deleting" — it complies, the session ends, and the next session makes the same mistake. Your corrections vanish; you pay for them again and again.

A typical moment

Without PD

You tell the agent: "Before changing multiple modules, confirm the scope first." It complies. A few sessions later, you are correcting it again.

With PD

Repeated behavioral evidence (the same correction, again)
        ↓
A behavioral pattern becomes reviewable
        ↓
PD proposes a principle
        ↓
You review the evidence, adjust the wording, approve it
        ↓
The principle can influence future sessions — injected into the agent's
context, or enforced through tool hooks
        ↓
The agent proactively presents a change scope and verification plan

If a principle later causes side effects, roll it back with one command.

PD does not promise that N corrections automatically produce a principle, and it never applies anything without you. It makes your repeated judgment durable instead of disposable.

How PD works

1. You correct the agent — or PD captures behavioral evidence through OpenClaw hooks (tool failures, risky edits, blocked operations).
2. Evidence is recorded locally as part of the agent's behavior history.
3. Recurring patterns become reviewable — you can inspect the raw evidence before deciding anything.
4. PD proposes a principle describing the behavior change.
5. You review, edit, approve, or reject. Nothing activates without owner approval.
6. Approved principles can influence future behavior — via context injection (prompt) or hook-based enforcement (code_tool_hook / RuleHost). You choose the channel; some corrections can also be deferred or archived instead of activated.
7. Everything is reversible — activated principles can be disabled or rolled back, with the evidence trail intact.

You stay in control

• No autonomous value decisions. PD only internalizes behavior you have reviewed and approved.
• Local-first. Evidence, principles, and decision logs live in your local workspace (files + SQLite). No cloud service required.
• Reversible by design. /pd-principle-rollback rolls a principle back and blacklists its pattern; implementation changes can be disabled or archived.
• Observable. /pd-status, /pd-samples, and /pd-export show what PD knows, what it proposed, and what you decided.

More than memory

Memory helps preserve what happened. PD focuses on turning behavioral evidence and owner feedback into explicit, reviewable guidance for how the agent should behave next time. PD does keep local records — but remembering history is the input; governing future behavior is the point. Every step of that governance stays reviewable and reversible.

Installation

Recommended — install from ClawHub

openclaw plugins install clawhub:principles-disciple

Then restart your OpenClaw gateway so the plugin loads.

Manual / npm installation

npm install principles-disciple

Requires OpenClaw >=2026.4.4 as a peer dependency.

Quick start

1. Run /pd-init to initialize the PD workspace files.
2. Work with your agent as usual — correct it as usual.
3. Run /pd-samples to see captured correction samples and review them (review approve|reject <sample-id>).
4. Run /pd-context to control what gets injected into agent context.
5. Run /pd-status for a single view of the system state.

Commands

All commands support short aliases for easier input:

| Short | Full Command | Description | |-------|--------------|-------------| | /pdi | /pd-init | Initialize workspace (generate PRINCIPLES.md, THINKING_OS.md, etc.) | | /pdb | /pd-bootstrap | Scan environment tools and suggest upgrades | | /pdr | /pd-research | Research tool upgrade solutions | | /pdh | /pd-help | Show all commands and usage guide |

| Command | Description | |---------|-------------| | /pd-status | View system status (GFI, Pain dictionary) | | /pd-pain | Report pain from the current OpenClaw session | | /pd-samples | List or review correction samples (review approve\|reject <sample-id> [note]) | | /pd-context | Control context injection [status|thinking|reflection|focus|preset] | | /pd-focus | Manage CURRENT_FOCUS.md [status|history|compress|rollback] | | /pd-principle-rollback | Roll back a principle and blacklist its pattern | | /pd-rollback | Roll back an empathy event penalty (<event-id>\|last) | | /pd-export | Export data [analytics|corrections --redacted] |

Advanced implementation lifecycle commands (/pd-promote-impl, /pd-disable-impl, /pd-archive-impl, /pd-rollback-impl) are semi-deprecated and kept for compatibility.

Configuration

The plugin accepts the following configuration options:

| Option | Default | Description | |--------|---------|-------------| | language | zh | Interaction language (en or zh) | | auditLevel | medium | Security guardrail level (low, medium, high) | | riskPaths | [] | High-risk directories requiring explicit authorization |

Advanced concepts

• Pain — PD's technical name for incoming behavior evidence: a user correction, tool failure, or blocked risky operation.
• Trajectory — the locally recorded stream of agent behavior and events.
• Reflection — generating principle proposals from evidence; output is always owner-reviewed.
• Evolution loop — the candidate → probation → active lifecycle of behavioral implementations.
• RuleHost / code_tool_hook — hook-based enforcement channel for approved principles.
• Context injection — feeding approved principles into the agent's context (see /pd-context).
• Thinking OS — optional thinking-model guidance injected into context (enable via /pd-context thinking on).

For the full architecture, runtime adapters (OpenClaw, Codex), and product boundary, see the project documentation linked below.

Security & data boundaries

Principles Disciple is a local-first behavior-governance layer. This section describes what this npm package (principles-disciple, the OpenClaw plugin) actually does, so you can evaluate it before installing. It reflects a source audit of the published artifact (PRI-547; updated 2026-08 for the optional anonymous product telemetry channel).

Local data

Behavior evidence, principles, decision records, and trajectories are stored in the user-controlled local workspace (flat files plus SQLite databases under the workspace's PD state directories). Governance state never leaves your machine. The only outbound data channel is the optional anonymous product telemetry described below, which is off by default.

Agent authority

PD influences future agent behavior through owner-approved context injection and tool-hook enforcement. Principle activation is subject to owner review; anything activated can be rolled back (/pd-rollback, /pd-principle-rollback).

Conversation and hook access

The plugin registers OpenClaw hooks (prompt, tool calls, LLM output, session lifecycle). Conversation access is granted through the host's hooks.allowConversationAccess config key. The npx installer and the plugin's first-load auto-fix set this key to true so the hooks work out of the box (PRI-343); you can turn it off with openclaw config set plugins.entries.principles-disciple.hooks.allowConversationAccess false — the plugin degrades to non-conversation surfaces (with a fallback trajectory collector) instead of failing.

Process and filesystem access

The plugin reads and writes PD workspace state (memory files, .state/, .principles/, SQLite databases) and observes tool-call activity through OpenClaw hooks — these capabilities are its stated behavior-governance function. The /pd-bootstrap command runs <tool> --version probes (rg, fd, shellcheck, …) to scan your local development environment; it only runs when you invoke it.

Network access

This plugin makes network requests in exactly two places:

1. Owner-configured LLM providers. Optional LLM calls happen only when you configure a runtime profile: the bundled provider SDKs read their standard credential environment variables (AWS/Azure/GCP/OpenAI-style, depending on the chosen provider) and call that provider from your machine. Diagnostics, principle refinement, and internal agents run through this user-configured provider.
2. Optional anonymous product telemetry (default: OFF). One minimized daily snapshot per workspace, sent only after you explicitly opt in — see the next section.

Some antivirus engines flag the bundled provider SDKs' environment-variable handling; that is disclosed here rather than obfuscated.

Optional anonymous product telemetry

Default: OFF. The plugin makes no telemetry network request at all unless the anonymous_product_telemetry feature flag is enabled AND you have run pd telemetry enable --confirm. Zero consent = zero telemetry network requests; this is enforced by transport-level gate tests, not just policy.

When opted in, the plugin sends one small HTTPS POST per workspace per day to https://principles-website.pages.dev/api/product-telemetry/snapshot containing only:

| Field | Content | |-------|---------| | schemaVersion, consentVersion | schema constants ("1") | | dailyTelemetryId | 32-hex identifier that rotates daily and is unlinkable across days and workspaces (derived from a local secret that never leaves your machine) | | bucketDate | UTC date (YYYY-MM-DD) | | pdVersion | PD version string | | hostKind | openclaw / codex / other | | milestones | six true/false/null flags: initialized, painObserved, principleObserved, activationObserved, presenceReceiptObserved, effectReceiptObserved | | reliability | one initializationFailed flag |

Never sent (enforced by a strict schema validator and a privacy-guard test that rejects unknown or content-bearing fields): conversation content, prompts, agent responses, principle or pain text, source code, file or workspace paths, file names, repository URLs, usernames, emails, hostnames, environment variables, error messages, stack traces, and any stable installation or workspace identifier.

Controls (pd = the Principles Disciple CLI):

pd telemetry status              # consent state, gates, last export status
pd telemetry preview             # exact outbound payload; nothing is sent
pd telemetry enable --confirm    # grant consent (required before anything sends)
pd telemetry disable --confirm   # deny consent and delete the local identity
pd telemetry reset --confirm     # rotate the identity (unlink future daily IDs)

The PD_TELEMETRY_DISABLED environment variable disables telemetry even when consent was granted, and export is automatically suppressed in CI, test, demo, and development environments. Telemetry failures never block or crash the plugin: bounded timeout, at most 5 attempts per workspace per day, fire-and-forget scheduling.

Sensitive-data redaction

PD redacts supported sensitive patterns before persistence — including known Windows and Unix paths, email addresses, and common token formats — and /pd-export redacts by default. This is not a general-purpose PII scrubber: automatic redaction does not yet cover phone numbers, credit cards, IP addresses, or other unknown PII. Remaining limitations are tracked in the project's security baseline.

Separately shipped components

Other PD components ship as their own packages and have their own boundaries: the create-principles-disciple installer downloads from the npm registry and installs files under ~/.openclaw/; pd-console is a local web console that performs npm registry update checks and user-initiated feedback submission when you use those features, and its startup also schedules the same gated opt-in telemetry export described above. They are not part of this plugin tarball.

Part of the principles monorepo

See the root README.md for the full project overview, and PRODUCT_IDENTITY.md for the canonical product definition.

License

Apache License 2.0 - LICENSE