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:
| Command | Purpose |
|---|---|
zephr init | Bootstrap — authenticates, seeds, admits a worktree |
zephr login | Device-flow authentication |
zephr status | Installation health and version |
zephr doctor | Diagnostic checks |
zephr remember | Write a memory (belief capture) |
zephr recall | Search memories |
zephr why | Explain a recalled item's provenance |
zephr verify | Verify version-chain integrity |
zephr timeline | Event timeline for a worktree |
zephr observations | List raw observations |
zephr role list|show|use | Manage agent roles |
zephr profile list|show|switch|clone|try|keep|revert | Fleet profile management |
zephr workspace | Workspace operations |
zephr skills show|install|check|sync|publish | Skill lifecycle |
zephr tools list|describe|run|validate | Tool surface introspection |
zephr memory tree|show|drift|audit|export|retract|forget | Memory management |
zephr continuity report|conflict|retract|migrate | Session continuity |
zephr sync | Synchronise state |
zephr hook | Hook management |
zephr daemon | Start/stop the local daemon |
zephr mcp | MCP server management |
zephr extension | Extension management |
zephr integrations list|install|remove|status | Integration pack management |
zephr agent | Agent operations |
zephr agent-card register|list|revoke | Agent identity cards |
zephr activate | Activation flow |
zephr constraint create|promote|shadow|smoke | Constraint management |
zephr files | File operations |
zephr share | Share beliefs |
zephr handoff | Cross-device session handoff |
zephr resume | Resume a handed-off session |
zephr preflight | Pre-flight checks |
zephr upgrade | Self-upgrade |
zephr uninstall | Clean removal |
zephr review | Review operations |
zephr signal | Signal operations |
zephr pod | Pod operations |
zephr grep|search | Code 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:
| Hook | When it fires |
|---|---|
onSessionStart | Session begins |
onSessionEnd | Session ends |
onUserPromptSubmit | A user prompt is submitted |
onPreToolUse | Before a tool call |
onPostToolUse | After a successful tool call |
onPostToolFailure | After a failed tool call |
onPreCompact | Before context compaction |
onStop | Agent 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
| Area | Gap |
|---|---|
zephr init zero-memory aha | Designed — authenticates first, should deliver value before credential prompt |
| Fleet credential sweep | Designed — no sweep or process revocation on profile change |
zephr status cloud path | Ships 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_idand 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
| Failure | Recovery |
|---|---|
| MCP server crash | Client reconnects; daemon restarts the server |
| Daemon unresponsive | zephr daemon stop followed by zephr daemon start |
| Scope violation | Re-admit the worktree with zephr init |
| Auth token expired | zephr login re-authenticates |
Related references
- Configure your client — exact MCP config shapes
- Security and privacy — trust model and scope binding
- Architecture — repository structure