Use your VEP Twin Brain in Claude Code

Connect one VEP employee twin so Claude Code automatically receives the relevant VEP facts as you work. Choose the twin, create one setup command, and paste it into your terminal. Teaching stays off unless you turn it on.

One command to connect

macOS, Linux, and Windows

Use-only mode available

Connect in three steps

1. Choose a twin and terminal

Open the VEP App Store, choose VEP Twin Brain Connector, select the twin you want Claude Code to use, then choose macOS / Linux or Windows PowerShell. You do not need to copy an API key.

2. Create and copy your setup command

Click Create setup command and copy the result. The command works once and expires soon, so create a new one for each computer.

3. Paste it into your terminal

Paste the command, run it, and answer the setup questions. The connector installs and configures itself without replacing your existing Claude Code settings or hooks.

What the command looks like on macOS / Linux

VEP_URL=https://vep.live TWIN_BRAIN_ENROLLMENT_TOKEN=vte_... bash -c 'curl -fsSL "${VEP_URL%/}/api/twin-brain/v1/skill/install.sh" | bash -s -- --enroll --onboard'

What the command looks like in Windows PowerShell

$env:VEP_URL='https://vep.live'; $env:TWIN_BRAIN_ENROLLMENT_TOKEN='vte_...'; $p=Join-Path $env:TEMP "vep-twin-brain-install.ps1"; Invoke-WebRequest -UseBasicParsing "$env:VEP_URL/api/twin-brain/v1/skill/install.ps1" -OutFile $p; $pwsh=(Get-Process -Id $PID).Path; try { & $pwsh -NoProfile -ExecutionPolicy Bypass -File $p -Enroll -Onboard } finally { Remove-Item $p -Force -ErrorAction SilentlyContinue }

The Windows path uses a native PowerShell client for query, context, teach, doctor, JSON, and documented error exits. It does not require WSL or Git Bash.

Check your connection

Run doctor if setup reports a problem or Claude Code cannot reach Twin Brain.

"$HOME/.claude/skills/twin-brain/twin-brain.sh" doctor

& "$HOME/.claude/skills/twin-brain/twin-brain.ps1" doctor

Technical installation details

The setup command contains a short-lived, single-use vte_ enrollment token, not a durable vtk_ API key. The installer redeems that token once over HTTPS, writes the read-only key to local config, and adds one Twin Brain UserPromptSubmit hook without replacing existing Claude settings or hooks.

Both platform installers download /api/twin-brain/v1/skill/package, verify the Ed25519 signature from /api/twin-brain/v1/skill/manifest, check the package sha256, and accept exactly five signed archive entries: SKILL.md, twin-brain.sh, twin-brain.ps1, user-prompt-submit.mjs, and the generated manifest.json. The separately served installers pin the same public key and fail closed before extraction.

What Claude gets automatically

Automatic facts are on by default. For each Claude Code prompt, the connector asks Twin Brain for facts relevant to that prompt and gives the complete matching set to Claude. It does not teach or change facts while doing this.

Technically, each prompt invokes the local UserPromptSubmit hook. The hook sends the bounded prompt to /api/twin-brain/v1/query with {"query": prompt, "answer": false} by default and adds the exact boolean "redact_secrets": true only when opted in, then injects the full relevance-ranked fact set selected for the real employee's boss-chat prompt. It sends no tenant or employee id: the API key defines that scope server-side.

The hook is read-only and never calls /teach. It uses short hard-capped network/process timeouts and fails open with empty output on missing config, auth/rate/server errors, malformed responses, or network failure, so Claude Code continues normally. Disable only the automatic path with TWIN_BRAIN_AUTO_QUERY=0; explicit query and owner-enabled teach commands remain available.

Complete facts, configurable presentation

The API and hook always fail closed on credential, unknown, missing, auth-category, and auth-trigger provenance before inline or file egress; this boundary cannot be disabled. Allowed non-credential facts and generated answers are verbatim by default because redact_secrets is omitted/false. Set TWIN_BRAIN_REDACT_SECRETS=1 to send "redact_secrets": true and redact fact/answer text server-side plus a final local token-pattern pass, or set TWIN_BRAIN_UNTRUSTED_ENVELOPE=1 to JSON-quote facts inside an explicit untrusted read-only data envelope.

Zero-loss overflow

If the complete context exceeds Claude Code's 10,000-character hook limit, the hook atomically writes all of it to a mode-0600 file under a mode-0700 local cache directory and injects a short instruction to read that file. It does not truncate overflowing facts. Set TWIN_BRAIN_CONTEXT_DIR to choose a different local directory; matching files older than 24 hours are cleaned up best-effort.

Prompt data flow

Prompt -> local hook -> HTTPS /query -> server-filtered scoped facts -> local Claude additionalContext or restrictive overflow file. The durable key stays in local config and is sent only in a request header. VEP may retain normal server-side /query usage/audit metadata, and Claude Code may retain injected context in its normal session transcript. The hook writes no prompt, key, or network-response logs; only oversized fact context is persisted temporarily as described above.

Use it day to day

Use mode use-only when Claude should receive facts but must not teach. Use query when you want to ask Twin Brain directly. Teaching remains off until an authorized user explicitly turns it on.

"$HOME/.claude/skills/twin-brain/twin-brain.sh" mode use-only
"$HOME/.claude/skills/twin-brain/twin-brain.sh" mode status
"$HOME/.claude/skills/twin-brain/twin-brain.sh" query "What should I know before replying to this customer?"
"$HOME/.claude/skills/twin-brain/twin-brain.sh" query --json "Return matching facts"
"$HOME/.claude/skills/twin-brain/twin-brain.sh" context --json "Current prompt"
"$HOME/.claude/skills/twin-brain/twin-brain.sh" learning status
"$HOME/.claude/skills/twin-brain/twin-brain.sh" learning on
"$HOME/.claude/skills/twin-brain/twin-brain.sh" learning off
"$HOME/.claude/skills/twin-brain/twin-brain.sh" teach "Customer prefers weekly Monday updates." customer_update_preference

Use the same subcommands through twin-brain.ps1 in Windows PowerShell.

mode use-only is the validated read-only sequence: it enables automatic facts, disables the local teach path before any network request, disables learning for the authenticated key's own server-bound twin, and reads the state back. It reports active only when the server returns strict OFF. A network, malformed-response, or contradictory-state failure leaves local teaching OFF and exits nonzero. The mode never calls /teach and accepts no target identifier.

Teaching is disabled by default. learning status reads the server-authoritative state. learning on|off changes only the authenticated key's own tenant/twin and accepts no target identifier. Both commands require the update response and a fresh read-back to match the requested state. ON updates the local preference only after both checks; OFF disables the local teach path before server verification. A legacy TWIN_BRAIN_LEARNING_REQUESTED=1 setting never enables learning.

This release covers self-toggle plus explicit teach only. Automatic passive learning from prompts or answers remains open and is not implemented; the prompt hook never calls /teach.

Security Model

The one-copy setup command embeds only a short-lived vte_ enrollment token.
The durable vtk_ key is returned once to the CLI during redemption and is never accepted in URLs.
The server stores only an HMAC hash of each key.
Every key is bound server-side to one tenant and one employee twin.
The connector manifest is signed with Ed25519 over deterministic canonical JSON.
The installer pins key id tb-ed25519-v1 out of band and fails closed on missing signatures, unknown key ids, manifest tamper, package tamper, or extra archive entries.
The installer preserves pre-existing settings and hooks byte-for-byte, updates only its marked hook group, writes atomically with restrictive permissions, and is idempotent.
SPKI SHA-256 fingerprint: 6b00bf9c2441609d8a0b92c794e2eb450df28f485b00fe83ec2b0708638aae31.
Primary distribution is the authenticated VEP App Store/CLI path. The curl installer is a convenience path with the same pinned-key verification.
Queries never return credential DNA.
Transparent context is facts-only, fail-open, never invokes teach or tools, and delivers oversized facts through a restrictive local file instead of truncating them.
Teach writes are external-provenance, lower-trust facts and are quarantined when a key is revoked.
The write path locks the same key row used by OFF before ingesting, so a write that resumes after OFF commits is rejected before DNA mutation.
Known credentials, contextual secret candidates, and ambiguous high-entropy token-shaped values are rejected before any DNA transaction; they are not redacted and stored.
A valid or stolen key can enable and poison lower-trust facts only for its own bound twin. It cannot select another tenant/employee; revoke or rotate suspected compromise to quarantine that key's writes.
The connector package intentionally excludes server routes, production code, data exports, and secrets.

Manage Keys

Use the App Store connector card to see existing connections, create a setup command for a twin you can access, and revoke connections you no longer use. For security, management responses never include the raw vtk_ secret after enrollment.

Troubleshooting

The setup command expired

Return to the App Store connector card and create a new setup command. Each command works once and expires soon.

Claude says it cannot connect

Run doctor. A 401 or exit 64 means the local TWIN_BRAIN_API_KEY is missing or invalid. A 403 or exit 65 means the connection is disabled, revoked, missing scope, or not authorized for that twin.

No Twin Brain facts appear

Run mode status and doctor. Automatic facts should be on; if the network or server is unavailable, Claude Code continues without Twin Brain context.

Teaching is blocked

Teaching is off by default. Run learning status to see the server-authoritative setting. A 429 or exit 69 means the key or IP reached its rate limit; retry later or ask the owner to adjust the cap.