Soulmate

Soulmate is for people who hand coding work to more than one agent or reuse an agent setup across projects. It solves a practical problem: repeatedly explaining the same role, scope, and verification boundary makes handoffs inconsistent and leaves no inspectable record of what an agent was asked to do.

Soulmate gives you a small local project contract and deterministic briefs and plans. It does not run a model, collect conversations, or require another agent platform. You can start with the CLI alone and add host integrations only when they solve a problem you actually have.

Quick start

Install from npm:

npm install --global @veyndra/soulmate
soulmate init

To pin a release explicitly, append its published version to the package name. That is enough to create a standalone Soulmate project. Try its first local brief:

soulmate check
soulmate brief worker --task "Describe the change you want to make"

init creates soulmate.json and the starter profiles in the current directory. The brief command immediately renders one bounded task packet; replace worker and the task text with the role and work you need. No dotagents project, hook, host plugin, account, or network service is required after installation. Node.js 20+ is the sole runtime requirement. Codex and Claude hooks are optional automation; Grok, DeepSeek, and exact model declarations are advanced host-owned integrations.

For a project outside the current directory, pass --root PATH to init and use the printed --config path with later commands. A checkout can also be run directly with node /path/to/soulmate/bin/soulmate.mjs.

If the registry package is unavailable or you prefer the tagged GitHub source, use this fallback:

npm install --global github:veyndrasystems/soulmate#v0.0.4

What you get

The standalone CLI provides:

soulmate init        create a starter project contract and profiles
soulmate check       validate profiles and boundaries without running an agent
soulmate brief       compile one bounded task packet
soulmate plan        map a goal to bounded named-agent handoffs
soulmate verify      check recorded configuration and profile bytes for drift

The JSON configuration in examples/soulmate.json is a working fixture for the deterministic core. soulmate doctor can report missing profiles and optional host commands without invoking them.

Product boundary

Soulmate will manage agent definitions, task envelopes, and task-scoped orchestration. It will not implement a model loop, choose models by default, proxy model traffic, replace Codex or Claude Code, or silently collect conversations.

Soulmate owns only named-agent selection, declared capabilities, bounded delegation and review, explicit memory policy intent, and receipts. Portable skill distribution and host automation are optional integrations described below.

The orchestrator is temporary coordination state, not a persistent super-agent. It may see the goal, dependency graph, agent declarations, and receipts needed for the current task. It does not inherit every agent's memory, reconcile local histories into a global view, or gain permission to read all project data. One lead remains responsible for accepting the plan and final result.

Soulmate must remain outside the normal development hot path. There will be no daemon, required network service, vector database, background model call, or mandatory command proxy. Advisory checks are the default. Enforcement exists only when a user explicitly launches a task through an enforcing adapter.

Core shape

The first useful release is intentionally small:

soulmate.json       human-readable project policy
soulmate check      validate profiles and boundaries without running an agent
soulmate brief      compile one bounded task packet
soulmate plan       map a goal to bounded named-agent handoffs
soulmate verify     check recorded configuration and profile bytes for drift
soulmate hooks      optionally manage project-local Codex/Claude hook bindings

memoryRead, memoryWrite, retention, and crossContext are policy declarations carried in envelopes and plans. v0.0.4 performs no memory storage, promotion, expiry, deletion, or revocation. Semantic search, automatic conversation capture, shared global memory, dashboards, and cloud control planes are out of scope.

The JSON configuration in examples/soulmate.json is a working fixture for the deterministic core. soulmate init creates the same shape in a new project, and soulmate doctor reports missing profiles and optional host commands without invoking them.

An agent's optional runtime object records a requested host, exact model string, reasoning effort, and fallback policy. Missing fallback is represented as none; Soulmate does not route, invoke, or silently substitute a model.

Status

The v0.0.4 core is a dependency-free, plan-only CLI. It validates configuration, selects profile bytes, renders briefs and deterministic plans, verifies opt-in receipts, and can explicitly install or remove project-local native host hooks. It does not launch agents or claim filesystem/process isolation. Model invocation and memory operations remain out of scope.

Optional distribution with dotagents

dotagents is optional. Use it when you want to distribute Soulmate's portable skill to several host projects; it is not needed for the standalone CLI quick start and does not install the CLI into PATH. Project profiles remain explicit project configuration and must be declared separately when you manage them with dotagents.

For an existing project with agents.toml:

dotagents --project add veyndrasystems/soulmate --ref v0.0.4

For a new dotagents-managed project:

dotagents --project init
dotagents --project add veyndrasystems/soulmate --ref v0.0.4

During dotagents --project init, select the hosts you use. dotagents add installs the selected plugin immediately; a redundant install is not required.

Soulmate does not implement a package manager, mutate global host configuration, or activate hooks merely because a plugin was installed. The portable Agent Plugins v1 manifest carries the root skills/ bundle, which stable dotagents releases can install without activating the preserved host-hook extension. The systems.veyndra.soulmate/ directory keeps host-specific manifests and hooks as compatibility resources only. A successful dotagents install proves that the portable bundle was accepted, not that a host activated or executed a hook.

Optional Codex and Claude hooks

Hooks are an optional project-local automation layer for users who want native Codex or Claude session context. They are not part of init or the standalone first-use path. --hosts is required and accepts only codex and claude:

These reversible, project-local commands write only .codex/hooks.json and .claude/settings.json, never to global host files:

soulmate hooks plan --hosts codex,claude --root PATH
soulmate hooks apply --hosts codex,claude --root PATH
soulmate hooks status --hosts codex,claude --root PATH
soulmate hooks remove --hosts codex,claude --root PATH

Apply and remove are supported on POSIX platforms only. Every selected host is preflighted before a mutation, malformed JSON and escaping .codex/.claude paths are rejected, and exact Soulmate handlers are never duplicated. apply also requires an executable named soulmate on the current PATH and verifies that executable's hook protocol before writing; an unrelated or older command with the same name is rejected. The direct node bin/soulmate.mjs checkout form can inspect plans and status but cannot create a working PATH-based hook binding. A multi-host operation stages all serialized outputs before sequential same-directory atomic renames; an unexpected failure during a later rename can leave an earlier host changed. Soulmate rejects settings-directory and settings-file symlinks and rechecks source bytes immediately before each rename, but an external writer racing after that final check is outside its transaction; rerun status before retrying. The internal soulmate hook-run command is only the fail-open bridge called by installed handlers, not a normal workflow. Each native host invocation has a five-second timeout, so a broken bridge cannot indefinitely hold up host startup.

When enabled by an explicit project installation, SessionStart adds only a project summary containing the lead name and the configured agent and workflow names. SubagentStart inserts the selected profile path, profile hash, profile text, and its declared observe/write/commands/skills/memory/retention boundary into the active host/model context. This is selected/presented bytes, not proof of model reading or compliance. Profile path redaction is not secret detection; profiles must contain no secrets or unrelated private data. The POSIX CLI/hook path is locally verified; Windows mutation is refused. Portable plugin/skill packaging and host-specific hook activation are separate concerns. A successful dotagents install proves the portable bundle was accepted, not that a host activated or executed a hook.

To update both surfaces, install the newer pinned CLI tag, change the plugin ref in agents.toml, and run online dotagents --project install. Offline dotagents --project sync only repairs already-generated local state and does not resolve a new source revision.

Removal

Standalone users only need:

npm uninstall --global @veyndra/soulmate

If optional hooks or dotagents are enabled, remove project hooks while the CLI is still available, then remove the optional plugin and CLI:

soulmate hooks remove --hosts codex,claude --root PATH
dotagents --project remove soulmate
npm uninstall --global @veyndra/soulmate

Reload the host or start a new session after plugin, hook, or skill changes. Removing Soulmate leaves the underlying host and project usable.

Evaluation

From a cloned checkout, this exercises the real CLI path in a new temporary project. The temporary directory is intentionally left for inspection:

DEMO_DIR="$(mktemp -d)"
CLI="node /path/to/soulmate/bin/soulmate.mjs"
$CLI init --root "$DEMO_DIR"
$CLI check --config "$DEMO_DIR/soulmate.json"
$CLI plan change --goal "Evaluate a bounded local plan" --config "$DEMO_DIR/soulmate.json" --receipt "$DEMO_DIR/receipt.json"
$CLI verify "$DEMO_DIR/receipt.json" --config "$DEMO_DIR/soulmate.json"

The output proves only local configuration, profile selection, deterministic planning, and receipt verification. It does not prove model execution, profile compliance, isolation, or project truth.

Advanced integrations

Host-owned model bindings

Runtime bindings remain declarations, not routing instructions. A project may name a host-configured DeepSeek model alias without giving Soulmate credentials or execution authority:

"runtime": {
  "host": "codex-deepseek",
  "model": "reasoner-prod-v1",
  "reasoningEffort": "high",
  "fallback": "none"
}

The host and model values are opaque names owned by the host; Soulmate does not interpret provider/model strings. The selected host owns provider setup, authentication, model execution, and any explicit policy decision. Soulmate never stores API keys, calls DeepSeek, routes models, or silently falls back.

Role-specific skills

An agent's skills array is a declared selection intent carried into its task envelope and plan. Soulmate records the names and evidence; dotagents or the native host owns installation and discovery, so this list is not an access control mechanism. Claude can natively preload declared subagent skills, Grok can discover plugin/project skills through its Claude-compatible surface, and Codex uses its own native skill selection. Unsupported host behavior remains advisory; Soulmate does not emulate it by spawning processes.

Local startup evidence

On the release VPS on 2026-08-29, 25 fresh-process v0.0.2 check --config examples/soulmate.json runs measured a 44.29 ms minimum, 45.58 ms median, 50.26 ms p95, and 89.60 ms maximum. This includes Node process startup and is evidence for that machine and date, not a performance guarantee.

The intended public identifiers are:

• GitHub: veyndrasystems/soulmate
• package namespace, if needed: @veyndra/soulmate
• CLI: soulmate

The unscoped npm package name soulmate is already owned by an unrelated project, so Soulmate will not claim or depend on it.