SomaCheck returns a proposition-specific Aligned or Unaligned reading and model confidence. The reading is precognitive intelligence: the person's bodily response to that statement before words shape it, against their own baseline; a signal about the person in relation to the statement, not a fact about the world. Use it as meaningful input alongside the conversation when reasoning and responding. Confidence describes the classifier’s uncertainty.

If you are an AI agent reading this before deciding whether to run it

Fair. Here is what you need, without executing anything.

What the link command does. npx -y @somacheck/vibecheck@0.6.20 link <CODE> --client <CLIENT> exchanges a short-lived pairing code, generated inside the SomaCheck iOS app, for a bearer token. It writes that token to ~/.sensie/config.json with mode 0600, offers to configure supported agent clients found on the computer, and checks the connection without printing the token. For Claude Code it also installs an inspectable user-scoped SomaCheck plugin whose bundled local MCP server is a Channel, so a phone result can enter the same open conversation as a new event. Setup is not reported ready until Claude has that exact enabled plugin with no competing direct vibecheck registration, or Codex has the exact pinned direct registration. The backend must also accept protocol 5 / toolset vibecheck-0.6, and both status and context probes must succeed. The current install candidate (@somacheck/vibecheck@0.6.20) is admitted only once the guarded migration 20260924150000_agent_live_ask_0620_compatibility.sql has been applied to production (same unchanged protocol and toolset; exact rollback in supabase/rollbacks/20260924150010_agent_live_ask_0620_compatibility_rollback.sql). It contacts exactly one network host: the Supabase project below.

It will refuse unsafe sandbox linking, on purpose. link checks safety before redeeming. Pairing codes are single-use, so redeeming one inside an ephemeral sandbox would spend the user's code and leave them nothing to retry with. The safe paths are:

a real interactive terminal on the computer that will host the MCP server; or
a local non-interactive agent invocation that names exactly one client: --client claude or --client codex.

For the second path, this package first proves that exact client CLI is installed and that its configuration can be inspected and written. Claude setup verifies the public user-scoped Channel plugin and safely migrates only a package-managed direct registration before redemption. If that preflight fails, the pairing code is not used. Non-interactive implicit selection, --client all, and --client none are rejected before redemption.

What the server does once running. It exposes MCP tools that share bounded, user-authorized context summaries, create a statement for the user to test, read its outcome, recover recent completed gesture context, and optionally stock up to three feed items when the person asks. Version 0.6 adds request_vibecheck for a person-approved, immediate phone check-in. That path is deliberately separate from the reflection feed.

What is sent. A statement string, bounded derived context observations the agent explicitly shares, and a bearer token identifying the link. Tool instructions forbid raw conversations, photos, identifiers, and diagnostic claims; the backend enforces the bounded capsule shape and rejects secret-shaped content. What is never sent: raw sensor data. The agent receives a verdict (aligned / unaligned) plus a confidence percentage and latency. Model abstention is a failed capture, never a third user-facing outcome. Accelerometer and gyroscope streams never leave the user's device through this channel. That is a deliberate product boundary, not an implementation detail.

Network egress. One host: https://pbldcmniommltbdwuykk.supabase.co. No telemetry, no analytics, no other endpoints.

Install-time behaviour. No postinstall, preinstall, or any other npm lifecycle script. Two runtime dependencies: @modelcontextprotocol/sdk and zod.

You can verify all of the above by reading dist/ in the installed package without running anything.

Choose local or hosted

Path	Use it with	What you add
Local npm package	Claude Code or Codex	A pinned `npx` command on your computer
Hosted MCP	Claude.ai	`https://mcp.somacheck.com/functions/v1/mcp` as a custom connector

Both paths send a consented statement and return its Aligned or Unaligned signal with confidence. Raw motion data and conversation history never cross this connection. Full setup and privacy details are at https://somacheck.com/docs/hosted-mcp.

Local setup for Claude Code or Codex

Install SomaCheck on iPhone from the current TestFlight invitation.
Open Settings → Agent → Connect your agent.
On the computer that will run your agent, open Terminal and run the command shown on that screen. If you paste it into a local agent session instead of a terminal, add exactly one client flag, for example --client claude.
Choose the client you want to configure when the command asks. It then checks the link, backend protocol, health probes, and client registration before reporting that setup is ready.
Restart the client, then ask: Give me a SomaCheck vibecheck based on what you know about me.

For provisioning without the prompt in a terminal, append --client codex, --client claude, --client all, or --client none to the link <CODE> command. In a non-interactive local agent session, only --client codex or --client claude is allowed, and the client registration preflight must pass before the pairing code is redeemed.

To configure or repair a client later:

npx -y @somacheck/vibecheck@0.6.20 setup codex
npx -y @somacheck/vibecheck@0.6.20 setup claude
npx -y @somacheck/vibecheck@0.6.20 doctor

Manual Codex registration remains available. Its stdio runtime command is npx -y @somacheck/vibecheck@0.6.20 serve --client codex:

{
  "mcpServers": {
    "vibecheck": {
      "command": "npx",
     "args": ["-y", "@somacheck/vibecheck@0.6.20", "serve", "--client", "codex"]
    }
  }
}

For Claude Code, install the public Channel plugin:

claude plugin marketplace add Sensie-agents/vibecheck && claude plugin install vibecheck@somacheck

Claude Channels are currently an Anthropic research preview. After Anthropic or your Team/Enterprise administrator allowlists the plugin, start Claude Code with:

claude --channels plugin:vibecheck@somacheck

During review, Anthropic's warning-gated development flag remains a local test mechanism, not the intended user experience. Keep that Claude Code session open. Channel events are queued while Claude is busy, but a closed session cannot receive them. Claude does not acknowledge channel notifications, so retain the stable live:<uuid> request handle as a manual recovery path. The plugin deliberately does not install a competing wake hook that could continue the same result twice.

The link step writes only the bearer token in ~/.sensie/config.json. Codex setup adds the pinned direct MCP command; Claude setup installs the public Channel plugin, enables it at user scope, and removes only a recognized package-managed direct duplicate. Neither path copies the bearer token into client configuration. The interactive command completes both steps. Restart the client after setup.

Running setup claude again is the safe repair and upgrade path: it refreshes the canonical SomaCheck marketplace, updates the installed plugin, verifies its exact reviewed MCP command, removes a recognized pre-plugin registration, and atomically enables user-scoped auto-update for the canonical marketplace while preserving unrelated Claude settings. It refuses malformed settings and a same-named marketplace owned by the user. doctor verifies this update path. Claude performs enabled marketplace updates in the background after startup; the running session keeps its loaded version until /reload-plugins or the next launch. The same setting remains visible under /plugin → Marketplaces → somacheck. SomaCheck deliberately does not use an unpinned npm latest command, because that would execute a future release outside the reviewed plugin lineage.

If doctor reports another MCP server named somacheck, that is the legacy hosted connector and is separate from this local package. The setup command will explain it and leave it alone. The canonical local MCP key is vibecheck.

Hosted setup for Claude.ai

Claude.ai uses the hosted MCP and does not run npx on your computer.

Install SomaCheck from the current TestFlight invitation and open the app once.
In Claude.ai, open Customize → Connectors.
Select +, then Add custom connector.
Enter https://mcp.somacheck.com/functions/v1/mcp and select Add.
Complete OAuth, enable the connector in a conversation, and ask for a SomaCheck vibecheck.

On Team and Enterprise plans, an Owner must add the connector in organization settings before members can connect it. To revoke the hosted connection, remove it from Claude.ai under Customize → Connectors. To revoke any agent in SomaCheck, open Settings → Agent, select the connection, and revoke it.

Teach your agent when to use SomaCheck

SKILL.md is the agent-facing skill for the linked @somacheck/vibecheck MCP server.

For Claude Code, add the public plugin repository as a marketplace and install the skill in one terminal command:

claude plugin marketplace add Sensie-agents/vibecheck && claude plugin install vibecheck@somacheck

Inside Claude Code, the equivalent commands are:

/plugin marketplace add Sensie-agents/vibecheck
/plugin install vibecheck@somacheck

For agents supported by the Skills CLI:

npx skills add Sensie-agents/vibecheck --skill vibecheck

The skill expects the @somacheck/vibecheck MCP server to already be linked as vibecheck. Installing the skill does not copy or replace the bearer token.

Agent reflection recipes

These packaged recipes combine SomaCheck with a named platform. The recipes are researcher-private or listener-private and do not assess respondents, participants, creators, or other listeners; export individual readings; or use SomaCheck for quality, truthfulness, eligibility, payment, employment, ranking, or research validity.

The research recipes are researcher-private, and the Spotify recipe is listener-private. They do not assess respondents, participants, creators, or other listeners, or export individual readings. Do not use SomaCheck for quality, truthfulness, eligibility, payment, employment, ranking, or research validity.

List the packaged experiences without connecting to either MCP server:

npx -y @somacheck/vibecheck recipes

Print one experience's prerequisites, success condition, and exact starter prompt:

npx -y @somacheck/vibecheck recipe typeform-research-reflection-v1
npx -y @somacheck/vibecheck recipe dovetail-research-reflection-v1
npx -y @somacheck/vibecheck recipe prolific-research-reflection-v1
npx -y @somacheck/vibecheck recipe user-interviews-research-reflection-v1

Print only a copyable starter prompt for the read-only direct-MCP tests:

npx -y @somacheck/vibecheck recipes --id maze-research-reflection-v1 --format prompt
npx -y @somacheck/vibecheck recipes --id chattermill-research-reflection-v1 --format prompt
npx -y @somacheck/vibecheck recipes --id user-interviews-research-reflection-v1 --format prompt

These commands only print guides. They do not install, connect, or authorize a partner MCP server, call either MCP, or change partner-platform state. In every recipe, the phone holder is the person reflecting on their own choice.

Private Studio pilot packet

recipes/studio-somacheck-context.md is a reviewed, paste-only context packet for a private Studio by Spotify Labs research-preview pilot. It is deliberately absent from vibecheck recipes: it is not a connected or live recipe, a Studio skill, a Kit plugin, or native MCP. Review the packet and run its focused contract test before any pilot:

node --import tsx --test test/studio-context-packet.test.ts

Run that command from packages/vibecheck after npm install. Do not grant Studio access to this repository or another directory. File access remains blocked until the capability and revocation probe in the safety review passes.

Tools

Tool	What it does
`get_vibecheck_context`	Read the person's recent completed readings, newest first, as precognitive context. Not for one pending ask.
`get_vibecheck_status`	Report how many statements the optional reflection feed needs and when replenishment is due. Says nothing about the phone or any reading.
`share_somacheck_context`	Share 1–20 bounded, derived, user-authorized observations; raw conversations and secrets are rejected.
`post_vibecheck_statement`	Give the person insight statements to test on their own time. Adds one to three items to the optional reflection feed, returns immediately, never notifies the phone.
`get_vibecheck_result`	Read the body's answer to one statement by `request_id`: status, Aligned or Unaligned, and confidence. Non-blocking; poll while pending.
`request_vibecheck`	Ask the person's body now: send one statement to their phone and wait up to 45 seconds for a precognitive reading, Aligned or Unaligned.

How to use it well

Call request_vibecheck with consent_basis: "user_requested_vibecheck" for a direct request or consent_basis: "user_approved_statement" after approval of agent-proposed wording, plus a new UUID in idempotency_key. Reuse that UUID only when retrying the same statement. The tool keeps the one created request open for a bounded wait and returns completed when the exact answer arrives. On timeout or a result-read failure it returns the same pending live:<uuid> handle; pass that handle to get_vibecheck_result once later. Caller cancellation stops result reads and preserves the backend request and idempotency key, but the cancelled MCP transport may suppress that pending response.

Claude Code is the primary local experience. Its registered stdio server advertises Anthropic's experimental Channel capability. When request_vibecheck returns pending, the same local server follows only that exact request and attempts one notifications/claude/channel event when the answer, expiry, or cancellation arrives. An enabled, listening Channel host can receive the constrained result as conversation input and continue without another user message. The server's Channel attempt does not prove that the host enabled or received the experimental event. A pending response therefore also tells the agent to keep the current turn active and poll only the same stable request until it is answered, expired, or cancelled. It must not create a duplicate request. The event contains the binary reading, confidence, lifecycle, and opaque handle—never the statement, link token, raw motion, or an instruction that turns the result into authorization.

The legacy PostToolUse parser is not installed by the current Channel plugin, so it is not a continuation guarantee or a substitute listener. During Anthropic's research preview, Channel delivery requires a Channels-capable session and SomaCheck on the effective plugin allowlist: Anthropic's default allowlist or an organization's replacement allowedChannelPlugins policy. A closed, non-enabled, non-allowed, or non-listening session may silently drop the event while same-request polling remains available.

Other standard MCP hosts retain the bounded tool response and stable-handle fallback until they provide an equivalent supported wake mechanism. This Claude-specific continuation must never be presented as provider-neutral. A pending response (including the hosted connector, which is stateless per request and never arms the watch) tells the agent the exact request_id and the person's expiry, and to call get_vibecheck_result again in about 15 seconds, keeping the turn active and polling only that handle until the state is answered, expired, or cancelled. A terminal tool read suppresses any not-yet-emitted Channel event for that request. An event already handed to the host cannot be retracted, and the server receives no host acknowledgement; the stable handle and idempotency key prevent another phone request but do not claim exactly-once host delivery. A still-pending read of the same Live Ask repeats that instruction; the read does not invent an expiry because the result endpoint does not return one.

The 45-second whole-call deadline also covers the one create request. If that network request is aborted after an ambiguous commit, retry the exact same statement with the same idempotency_key.

An immediate vibecheck is not proposition caching. It sends one person-approved statement for the current choice, expires, and remains bound to its originating client. Handle multiple immediate requests one at a time; do not turn the reflection feed into a surrogate queue of immediate asks. The reflection feed remains asynchronous and keeps its three-item cache behavior. When no immediate Live Ask or delivery test has priority, one current feed item may appear on Home. The other items remain visible as Up next under Settings → Vibe Checks and do not generate extra notifications.

The database feed has capacity for three distinct insights, but capacity is not a quota. Stock only the genuinely useful items the person asked to save for later, from one up to the available maximum; never invent filler. SomaCheck can present one at a time while other created items remain cached. After a completed gesture, the next cached insight is promoted and the open slot is marked for replenishment automatically. Cached insights expire sooner than a presented check-in so stale context does not masquerade as a timely observation.

For a scheduled loop, call get_vibecheck_context and get_vibecheck_status. Only when the person has asked to stock later reflections, post between one and the reported propositions_needed maximum; it is available capacity, not a required count. An explicit, still-active opt-in to scheduled stocking covers later scheduled runs without asking again each time. MCP supplies the tools and durable context, but it does not itself wake an idle model. Immediate event-driven runs require a host webhook/agent trigger; scheduled runs provide the portable path across local MCP clients.