Psyche settings reference
This page owns settings grammar and application details; the public settings
action remains SHOW-only.
Settings SHOW
psyche(action="settings", input={}, reasoning="inspect Psyche prompt configuration")
The result has exactly six rows in this order: pad, pad_file,
base_prompt, base_prompt_file, covenant, covenant_file. Every row has exactly key, current, default, configurable, and comment; both values are always <redacted>, including
empty/null defaults. It reports the last successfully applied reconstruction,
not ambient edits. All six rows are configurable, but SHOW is not a content
comparison: even after a successful change it remains fully redacted. A failed
reconstruction preserves that snapshot; provider failure returns only the fixed
SETTINGS_UNAVAILABLE failure, never partial rows or parser details. The complete
SHOW response also has the generic 65,536-byte UTF-8 bound.
Owner document
settings/psyche.json is optional. If present, it is a stable-read UTF-8 JSON
object beginning {"schema_version": 1, ...} with only the four string fields
base_prompt, base_prompt_file, covenant, covenant_file. Duplicate/unknown keys, wrong versions/types, invalid
UTF-8/JSON, Boolean versions, symlinks/non-regular files, reads over 64 KiB, races, and I/O
failures reject the candidate before prompt publication. There is no environment
layer, mutation action, migration, or writeback.
For each pair, a readable *_file wins; a missing file falls back to inline.
~ expands and relative pointers resolve against the agent workdir. Edit this
owner through shell (verify an exact replacement target exists once before
changing it, and verify the written JSON afterwards), then apply atomically with
context.rebuild (or refresh/molt), after explicit configuration authorization. Legacy top-level
init spellings for these four fields are inert; external writers must emit
this owner document. Before an authorized upgrade/reconstruction, preserve and
transfer any still-needed legacy values into it: the runtime never migrates them.
Base/covenant may fall back to existing mirrors. comment/comment_file are
unknown fields: remove them from old configs and put desired instructions in
system/pad.md through an authorized edit. No automatic rewrite or migration occurs. Invalid owner input is rejected before refresh teardown;
failed final publication restores the prior prompt generation, mirrors and SHOW.
Pad seeds are different: top-level init.json pad/pad_file remain their owner;
they are not fields in settings/psyche.json (which rejects them). There is no
environment layer for them. Edit the authorized seed source or its referenced
file; full reconstruction resolves it again. To change a nonempty durable Pad,
edit system/pad.md instead—changing its configured seed will not overwrite it.
Setting pad
Configured initial Pad seed; default "". pad_file wins when readable,
otherwise inline pad; reconstruction seeds system/pad.md only when missing or
empty and never overwrites a nonempty durable Pad.
Setting pad file
Initial Pad pointer; default null, resolved against workdir. It is still only a
seed for a missing/empty Pad.
Setting base prompt
Optional third-party prompt body; default ""; nonempty content mirrors to
system/base_prompt.md.
Setting base prompt file
Optional pointer; default null; a readable file wins over inline.
Setting covenant
Optional protected operator contract; default ""; nonempty content mirrors to
system/covenant.md.
Setting covenant file
Optional pointer; default null; a readable file wins over inline.