Zephr Docs

Surfaces

surfaces owns every place a human or a host process touches Zephr from outside the service: the CLI, the hook transport, the daemon, layered configuration, the MCP server endpoint, and how all of that is packaged and shipped.

Status

Evolving. The CLI ships with a comprehensive command surface. The MCP server is production stable. The daemon ships for local mode. Editor integration is limited to the adapter SDK path (Claude Code, OpenCode, Cursor). The zephr init zero-memory aha flow is designed but not shipped — the current implementation authenticates first, which the design spec identifies as the largest activation leak.

What ships

CLI (zephr)

The CLI is the primary human interface. All commands produce structured JSON with --json and non-zero exit codes on failure. The following top-level commands ship:

CommandPurpose
zephr initBootstrap — authenticates, seeds, admits a worktree
zephr loginDevice-flow authentication
zephr statusInstallation health and version
zephr doctorDiagnostic checks
zephr rememberWrite a memory (belief capture)
zephr recallSearch memories
zephr whyExplain a recalled item's provenance
zephr verifyVerify version-chain integrity
zephr timelineEvent timeline for a worktree
zephr observationsList raw observations
zephr role list|show|useManage agent roles
zephr profile list|show|switch|clone|try|keep|revertFleet profile management
zephr workspaceWorkspace operations
zephr skills show|install|check|sync|publishSkill lifecycle
zephr tools list|describe|run|validateTool surface introspection
zephr memory tree|show|drift|audit|export|retract|forgetMemory management
zephr continuity report|conflict|retract|migrateSession continuity
zephr syncSynchronise state
zephr hookHook management
zephr daemonStart/stop the local daemon
zephr mcpMCP server management
zephr extensionExtension management
zephr integrations list|install|remove|statusIntegration pack management
zephr agentAgent operations
zephr agent-card register|list|revokeAgent identity cards
zephr activateActivation flow
zephr constraint create|promote|shadow|smokeConstraint management
zephr filesFile operations
zephr shareShare beliefs
zephr handoffCross-device session handoff
zephr resumeResume a handed-off session
zephr preflightPre-flight checks
zephr upgradeSelf-upgrade
zephr uninstallClean removal
zephr reviewReview operations
zephr signalSignal operations
zephr podPod operations
zephr grep|searchCode search from the CLI

MCP server (zephr-mcp)

The MCP server speaks stdio JSON-RPC to the client that launched it. It advertises all tools from the generated MCP catalog via tools/list and dispatches via tools/call.

Transport: stdio (local mode), Streamable-HTTP (cloud mode via apps/web).

HTTP headers and conformance: On Streamable-HTTP responses, Zephr announces the server protocol revision via X-Zephr-Server-Version (and legacy alias Mcp-Server-Version). Note that server version headers are Zephr-private extensions rather than MCP specification-mandated headers. In strict conformance mode (ZEPHR_MCP_STRICT_CONFORMANCE=1), Zephr omits private extension headers so standard MCP conformance checks pass cleanly.

Tool tiers: tools are classified into core, search, docs, review, extension, and hosted tiers. Each role carries an allowedTiers array; a tool call is rejected with tier_denied if the role's tiers do not include the tool's tier.

Mutation surface: the server tracks a MUTATING_TOOL_NAMES set. Hosted tools are classified as read_only (metered read-only via tool-proxy; no durable store write).

Daemon (zephrd)

The local daemon persists between sessions and handles:

  • Hook transport (JSONL spool of lifecycle events)
  • Background sync
  • Health reporting

The daemon does not perform network egress in local mode.

Editor integration (adapter SDK)

The @zephr-ai/adapter-sdk package provides the required LifecycleAdapter contract:

HookWhen it fires
onSessionStartSession begins
onSessionEndSession ends
onUserPromptSubmitA user prompt is submitted
onPreToolUseBefore a tool call
onPostToolUseAfter a successful tool call
onPostToolFailureAfter a failed tool call
onPreCompactBefore context compaction
onStopAgent execution stops

Fleet profiles

Fleet profile projection writes supported clients to their native configuration. Claude Code uses ~/.claude/settings.json and project .mcp.json; OpenCode uses ~/.config/opencode/opencode.json; Cursor uses ~/.cursor/mcp.json. Codex has no supported JSON projection target.

Status: canonical profile and client projection ship. Credential-reference sweep and process revocation are designed but not built.

What is evolving

AreaGap
zephr init zero-memory ahaDesigned — authenticates first, should deliver value before credential prompt
Fleet credential sweepDesigned — no sweep or process revocation on profile change
zephr status cloud pathShips locally; cloud status relies on the hosted deployment

Setup and configuration

Local mode

Build the CLI from this repository; it is not published to npm. Authenticate with zephr login, run zephr init, then use zephr connect with its documented options to configure the admitted worktree.

Cloud mode

Interactive authentication uses zephr login device flow. API clients use separately minted bearer credentials against documented cloud routes.

Data flow

Human → CLI → zephrd (daemon) → MCP server (stdio/HTTP) → Core (SQLite/Postgres)
                              ↕
                        Hook transport (JSONL spool)

Persistence and security

  • Local: single SQLite file per installation. No encryption at rest (Zephr does not apply its own layer; use encrypted filesystem if needed).
  • Cloud: Postgres with RLS. Every tenant-scoped table carries an explicit installation_id and composite FK chain.
  • Scope binding: tool calls outside the admitted worktree are rejected with scope_violation. The scope is minted by a trusted issuer and carries an unforgeable brand.
  • Network: default local operation performs no network egress; login, cloud-backed operations, and configured remote providers are explicit exceptions. Cloud mode egresses only to the Zephr API and metered external providers.

Limits

  • CLI commands require Node.js 20+; the MCP app requires Node.js 22+.
  • Fleet profile projection supports only clients with registered projection targets.
  • The daemon requires the worktree to be accessible on the filesystem.

Failures and recovery

FailureRecovery
MCP server crashClient reconnects; daemon restarts the server
Daemon unresponsivezephr daemon stop followed by zephr daemon start
Scope violationRe-admit the worktree with zephr init
Auth token expiredzephr login re-authenticates