-
Notifications
You must be signed in to change notification settings - Fork 0
Installation
Zeref OS v2.6 installs as a Claude Code plugin. Other harnesses (Cursor, Aider, Windsurf, Gemini, Codex) read AGENTS.md directly via per-harness stubs.
claude plugin marketplace add kanadhiayash/zeref-os
claude plugin install zeref-os@zeref-osThe plugin lands at ~/.claude/plugins/cache/zeref-os/zeref-os/.
claude plugin list | grep zeref-os
# zeref-os@zeref-os v2.6.1 enabled
cd ~/my-project
claude
> /zeref-os:startExpected output:
Project: <name>
Last session: <iso> (or "never" on first run)
Active decisions: <N>
Open questions: <N>
Conflicts: <N>
Privacy mode: abstract
Model tier: Sonnet (auto-detected)
Always-on context: ~3k tokens
What do you want to work on?
cd ~/.claude/plugins/cache/zeref-os/zeref-os
python3 scripts/zeref-validate.pyExpected:
Zeref OS validator — <plugin path>
Skills: 14/14 (from zeref-registry.json)
Agents: 6/6
Commands: 8/8
Team packs: 6/6
Config: 5/5
Root privacy: 3/3 (PRIVACY, REDACT, SHARING_POLICY)
v4x canon: 6/6
Harness stubs: 3/3
Memory layout: flat
PATTERNS lint: 0 finding(s)
✔ Validation passed
Each harness reads its own stub; the stub defers to AGENTS.md.
Codex reads AGENTS.md natively. Just point it at the project root.
Cursor reads .cursor/rules/zeref.mdc. The stub instructs Cursor to load AGENTS.md.
ls .cursor/rules/zeref.mdcWindsurf reads .windsurfrules. Same pattern.
Aider reads .aider.conf.yml. An example is at .aider.conf.yml.example — copy + adjust.
cp .aider.conf.yml.example .aider.conf.ymlReads GEMINI.md natively. Defers to AGENTS.md.
AGENTS.md-native. No additional stub required.
Full table: references/harness-translation-map.md.
On first /zeref-os:start in a fresh project (no config/PROJECT.md):
-
project-setupskill auto-invokes - Interview captures: project name, parent project (optional), privacy mode (default
abstract), model tier (auto-detect), budget warn-at threshold - Writes:
config/PROJECT.md,PRIVACY.md,REDACT.md,SHARING_POLICY.md,config/PERMISSIONS.md,config/PARENT_SYNC.md(if parent),config/BUDGET.md - Prompts re-run
/zeref-os:startto boot the session
If user cancels mid-interview: Zeref OS boots in READ-ONLY mode until the schema completes.
zeref/ Python runtime provides CLI + dashboard + structured queries:
cd ~/.claude/plugins/cache/zeref-os/zeref-os
pip install -e .
python3 -m zeref --helpAvailable commands:
zeref status # print hot.md summary
zeref write-decision # append to DECISIONS.md (with PII scrub)
zeref grade <claim> # invoke evidence-grader logic
zeref audit # structural validation + privacy audit
zeref init # scaffold memory + config
zeref dashboard # render HTML score dashboard
zeref db-status # report backend (sqlite/duckdb) + parquet availability
claude plugin uninstall zeref-os@zeref-osmemory/ and config/ files in your project remain intact (per R2 non-deletion). To fully purge:
rm -rf memory/ config/PROJECT.md PRIVACY.md REDACT.md SHARING_POLICY.md| Symptom | Likely cause | Fix |
|---|---|---|
unknown event type 'X' in PATTERNS lint |
Custom event type added | Either add to EVENT_SCHEMA in scripts/zeref-validate.py OR rename event |
memory/sync/outbound/handoff-*.md missing on cross-model handoff |
caveman-handoff skipped |
Confirm _shared/model-resolver.md is present + brief diff complete |
| Gate output missing from PATTERNS.jsonl | Agent skipping gates | Validator warning surfaces this advisory; check session for skipped gates |
| Cyrillic-а in path detected, blocking handoff | NFKC + homoglyph guard fired | Replace with ASCII; user confirm if intentional |
- Architecture — full system overview
- FAQ — common questions
-
AGENTS.md— canonical spec -
references/harness-translation-map.md— per-harness install - Notion Command Center
Getting Started
Architecture
- Architecture · 14 skills · 4 gates
- Memory-Model · flat + PATTERNS schema
- Privacy-Model · 3 modes + R6
- Team-Packs · 6 on-demand
- Pattern-Detection · Two-Strikes
Reference