Claus

Claus creates local AI-agent sessions for Claviz apps.

It downloads a Claviz app into a temporary local workspace, adds agent instructions, examples, profiles, and helper commands, then opens the workspace in the tool selected by the user.

Philosophy

Claus is filesystem-agent-first.

Agents are already strongest at reading, editing, and validating code in a local filesystem. Claus should expose Claviz as a local editable project and let agents work with files directly.

Keep entity work file-native:

• Entity source of truth inside a session is workspace/.
• Agents create, edit, rename, and delete entity JSON/script files.
• Claus detects filesystem CRUD by comparing the workspace to .claviz/entity-manifest.json.
• Commands synchronize, validate, inspect, refresh, and protect the workspace.
• Commands should not become the primary entity editing interface.

Avoid adding command APIs such as create component, update function, or delete screen that make agents manipulate entities through a custom tool language. That is a step backward unless the command still produces normal editable workspace files and the agent remains free to inspect and modify them.

For facts, keep writes file-mediated: create or edit local draft JSON, diff it, then apply it. Read-only tools such as logs and fact search are fine because they provide context without replacing filesystem editing.

Requirements

• Node.js 18 or newer.
• A Claviz instance URL.
• A valid Claviz auth token.
• An AI coding tool or editor command installed locally, for example codex, claude, cursor ., or code ..

Usage

Run Claus with a Claviz URL, token, and the command to open after the session is ready:

npx @claviz/claus https://your-claviz-instance <token> --open "codex"

Other examples:

npx @claviz/claus https://your-claviz-instance <token> --open "claude"
npx @claviz/claus https://your-claviz-instance <token> --open "cursor ."
npx @claviz/claus https://your-claviz-instance <token> --open "code ."

Each run creates a new session under:

~/Claviz Sessions/

At startup Claus records the current Claviz user and working branch in .claviz/session.json. Entity publishing is blocked on master, and publish/fact-apply commands refuse to write if the user switched branches after the session was created. A clean session can be refreshed onto the current branch.

Session Commands

Inside a generated Claus session:

npm run status
npm run facts -- find
npm run logs -- failures
npm run validate
npm run publish
npm run refresh
npm run discard

publish applies filesystem entity CRUD from workspace/ back to Claviz. Created files create entities, edited files update entities, and deleted entity JSON files delete entities. Fact data changes use the separate safe draft workflow exposed through npm run facts. Runtime diagnostics use read-only Loki helpers exposed through npm run logs.

refresh reconnects an existing session to the current Claviz branch when there are no pending local changes. It re-downloads the workspace, rebuilds indexes/manifests/profile hints, clears old fact diff markers, and keeps fact drafts.

discard removes pending local session/workspace changes and keeps fact drafts. Use it before refresh when the user switched branches and explicitly wants to throw away local work.

Package Contents

• claus.js: CLI entry point.
• lib/: session, entity sync, fact tools, log tools, and profile indexing.
• docs/AGENT-GUIDE.md: embedded guide copied into generated agent instructions.
• examples/: known-good component/function/collection/entity patterns copied into sessions.
• profiles/: collection-specific guidance copied into sessions and surfaced by fact commands.

Development

Install dependencies:

npm install

Run the local checkout without publishing:

node claus.js https://your-claviz-instance <token> --open "codex"

Inside a generated session, Claus writes npm scripts that point back to this local checkout, so npm run status, npm run facts, npm run logs, npm run validate, npm run publish, npm run refresh, and npm run discard use your working tree.

.claviz/entity-index.json is the agent's navigation map. It includes aliases, direct references, reverse references, dependency ids, dependent ids, parent folder data, and folder children so agents can inspect usage before editing or deleting entities.

Useful checks:

node --check claus.js
node --check lib/session.js
node --check lib/facts.js
node --check lib/logs.js
node --check lib/profiles.js
npm pack --dry-run

For local testing, create a Claus session from a real Claviz instance and use a non-production app when possible. Session workspaces and fact drafts are generated outside this repository under ~/Claviz Sessions/.

When changing write behavior, keep the branch model explicit: entity changes cannot be published on master, fact writes can run on master, and remote writes should verify that the live Claviz branch still matches the session branch. Entity sync is file-native: workspace/ CRUD is translated into Claviz CRUD by comparing .claviz/entity-manifest.json with the current workspace.

Agent Guide

Do not put runtime instructions for generated agents in this README. Put them in docs/AGENT-GUIDE.md; Claus embeds that file into generated AGENTS.md and CLAUDE.md.

Keep docs/AGENT-GUIDE.md profile-neutral. Collection-specific names, business-domain rules, and product-specific workflows belong in profiles/<profile-name>/, not in the base guide. The base guide may explain how agents should discover and use profiles, but profile details should not leak into generic Claus instructions.

Keep generated-agent response rules user-facing. The agent guide may teach internal commands, but final responses to Claviz users should use Claviz-facing language such as "ready to apply to Claviz" and avoid npm/git/workspace details unless the user asks for them.