Pulse

A consent-aware nervous system for AI agents.

Pulse connects live Wear OS heart-rate data and Android conversation transcripts to AI agents through the Model Context Protocol (MCP). Agents can observe a session, derive evidence-backed speech and stress signals, review synchronized reports, and deliver coaching responses through the wearer's phone.

[!WARNING] Pulse is an experimental prototype, not a medical device. Its stress signal is a deterministic heart-rate heuristic and must not be used for diagnosis, treatment, safety-critical decisions, or emergency response.

Why Pulse?

Most AI agents only know what a user types. Pulse gives an agent a real-time, session-scoped view of what is happening around the wearer:

• Live physiological context from Wear OS Health Services, including freshness and sensor availability.
• Conversation context from streaming transcription, with pace, turn length, and silence metrics.
• Deterministic stress signals derived from heart-rate changes rather than opaque model inference.
• Durable event delivery across watch, phone, and backend disconnects, with acknowledgements and duplicate suppression.
• MCP-native access through typed resources, tools, prompts, and an interactive session-report widget.
• On-demand coaching requested from the watch and delivered after conversational silence.
• Hardware-free development through canonical fixtures and simulated device actions.

How It Works

flowchart LR
    W[Wear OS watch<br/>heart rate + requests] -->|Wear Data Layer| P[Android phone<br/>queue + transcription]
    P -->|WebSocket events| B[Pulse backend<br/>validation + SQLite]
    B --> S[Session intelligence<br/>stress + speech metrics + reports]
    S --> M[NitroStack MCP server]
    M --> A[AI agent / MCP host]
    A -->|coaching action| B
    B -->|TTS command| P
    P -->|spoken advice| E[Wearer]

The phone owns the session clock and durably queues events. The backend validates strict versioned contracts, stores events transactionally, indexes final transcripts with SQLite FTS5, and derives repeatable session metrics. The MCP server exposes that state without coupling the device pipeline to a specific agent host.

Quick Start

The default configuration uses fixture events, simulated vitals, and simulated device actions. No watch, phone, cloud API key, or native build toolchain is needed.

Prerequisites

• Node.js 20 or 22 LTS
• npm 9 or newer
• NitroStudio for interactive MCP testing

1. Install

git clone https://github.com/tejasai2007/pulse.git
cd pulse
npm ci
npm --prefix src/widgets ci

Create the local environment file:

cp .env.example .env

On Windows PowerShell, use Copy-Item .env.example .env instead.

The sample binds the backend to 0.0.0.0 so physical devices can reach it. For simulator-only use, set BACKEND_HOST=127.0.0.1 in .env before starting the backend.

2. Start Pulse

Run the backend and NitroStack development environment in separate terminals:

npm run dev:backend

npm run dev

The backend is reachable locally at http://127.0.0.1:8787. Check its runtime health:

curl http://127.0.0.1:8787/health

Without OPENAI_API_KEY, the health response reports the copilot provider as degraded and uses deterministic fallback advice; the local fixture path remains available.

3. Send Fixture Events

In a third terminal:

npm run mock:events

Each event prints a JSON acknowledgement. The fixture creates session-fixture-001 with one simulated heart-rate sample and one final transcript segment. Event IDs are stable and deduplicated, so rerunning the command is safe.

npm run dev keeps TypeScript and the widgets rebuilt, but it does not launch the MCP entry point. Open the project in NitroStudio and launch dist/index.js. For a stdio MCP host, run npm run build, set its working directory to the cloned repository, and configure the host command as node --env-file=.env dist/index.js.

Then try:

• phase_zero_probe with message: "hello" to verify MCP connectivity.
• session://latest/transcript to read the fixture transcript.
• search_sessions with status: "calibrating" to find the fixture session.
• generate_session_report with sessionId: "session-fixture-001" to render the report widget in a compatible host.

MCP Surface

Resources

Resource	Purpose
session://latest/transcript	Most recently ingested final transcript segment
session://current/transcript	Ordered transcript for the current session
session://{sessionId}/transcript	Stored transcript for a selected session
session://current/vitals	Consent-checked latest BPM, freshness, and rolling window
session://current/stress	Consent-checked deterministic stress state and supporting metrics
session://current/speech-metrics	Speech pace, longest turn, and current silence
session://current/context	Consent-checked wearer-provided goals and boundaries
session://{sessionId}/report	Synchronized session summary and evidence timeline

Tools

Tool	Purpose
get_current_session_metrics	Read live vitals, stress, and speech metrics together
get_current_transcript	Read a bounded selection of current transcript segments
search_sessions	Search transcript text, dates, and lifecycle status
generate_session_report	Build an evidence-only report for a stored session
haptic_nudge	Request a predefined haptic intervention
whisper_coach	Queue TTS coaching after conversational silence
get_pending_copilot_request	Claim an advice request initiated from the watch
copilot_advice	Deliver grounded advice for a claimed request
phase_zero_probe	Verify connectivity between an MCP host and Pulse

Pulse also provides the review_session and handle_copilot_request prompts. Canonical schemas and delivery semantics are documented in docs/contracts-v1.md.

Conversation Copilot

Conversation Copilot supports two execution modes:

• COPILOT_MODE=automatic asks an OpenAI-compatible Responses API for one concise suggestion. Set OPENAI_API_KEY only on the backend. Requests use store: false, and deterministic metric-based advice is used if no key is configured or the provider fails. The current system prompt is specifically tailored to presenting Pulse on stage, not general conversations.
• COPILOT_MODE=mcp leaves reasoning to an MCP host. The host claims the watch request, reads the consented session evidence, and responds through copilot_advice. The current Android flow does not create session context or grant read:context, so context-dependent MCP mode requires those events to be supplied separately.

Set COPILOT_ENABLED=false to disable watch-requested advice. Backend-queued TTS pauses transcription, waits for 1.5 seconds of conversational silence, plays through the selected phone audio route, and then resumes capture. Local probe and heart-rate alerts speak immediately.

Android and Wear OS

Additional Prerequisites

• Android Studio with Android SDK 35
• JDK 17
• Android phone running API 31 or newer
• Wear OS device running API 30 or newer with Health Services and Google Play services
• A paired phone and watch; Bluetooth earbuds are optional
• A Deepgram API key for live cloud transcription

Open android in Android Studio and add machine-specific values to the ignored android/local.properties file:

BACKEND_URL=http://10.0.2.2:8787
VITALS_SOURCE=simulated
AUDIO_INPUT=phone
TRANSCRIPTION_MODE=fixture
# DEEPGRAM_API_KEY=restricted-development-key

10.0.2.2 reaches the host machine from an Android emulator. A physical phone must use a backend URL reachable on its network, such as http://192.168.1.10:8787. Debug builds allow local cleartext traffic; release builds require HTTPS/WSS.

From the android directory, build and install both apps:

.\gradlew.bat :phone:installDebug :watch:installDebug

On macOS or Linux, use sh ./gradlew (the tracked wrapper is not executable).

For the real device path:

1. Set VITALS_SOURCE=watch in android/local.properties.
2. Add a restricted development DEEPGRAM_API_KEY to enable Deepgram streaming. It is compiled into every APK variant, so never use a production credential or distribute that APK.
3. Point BACKEND_URL at the reachable Pulse backend.
4. Grant microphone permission on the phone and health/body-sensor permissions on the watch.
5. Start a session from either device and verify watch, backend, and audio-route status on the phone.

The watch captures heart rate through a foreground Health Services exercise session. It sends urgent Data Layer items to the phone and retains unacknowledged samples across temporary disconnects. The phone persists its backend replay queue and reconnects with bounded backoff.

[!NOTE] The Android app currently ignores TRANSCRIPTION_MODE: when microphone permission and foreground startup allow capture, a non-empty DEEPGRAM_API_KEY enables Deepgram streaming. On-device transcription is not implemented, and fixture transcripts come from npm run mock:events, not from Android. DEVICE_ACTIONS is a backend setting; Android's generated value is unused. Real backend-triggered watch haptic delivery is also incomplete.

[!CAUTION] The phone currently triggers a local watch vibration and spoken warning after heart rate remains above 85 BPM for 10 seconds outside exercise mode. This prototype alert does not check MCP consent scopes or DEVICE_ACTIONS and is not medically validated. Do not use the real-vitals path with people until this behavior has been reviewed or disabled.

Hardware validation steps and the latest recorded results are in docs/phase-zero-results.md.

Session Report Widget

The report tool is connected to an MCP Ext App built with Next.js and React. To develop it separately:

npm --prefix src/widgets ci
npm --prefix src/widgets run dev

The development server runs at http://localhost:3001. Build it with:

npm --prefix src/widgets run build

Configuration

Copy .env.example to .env for development defaults. The default BACKEND_HOST=0.0.0.0 exposes the unauthenticated backend to the local network; use 127.0.0.1 when device access is not required.

Variable	Default	Description
NODE_ENV	development	Runtime environment
LOG_LEVEL	info	debug, info, warn, or error
NITROSTACK_APP_MODE	universal	NitroStack process mode used by the local development path
BACKEND_HOST	0.0.0.0	Backend bind address
BACKEND_PORT	8787	Backend HTTP/WebSocket port
BACKEND_URL	http://127.0.0.1:8787 in .env.example	Backend URL used by the MCP server and fixture sender
DATABASE_PATH	data/pulse.sqlite	SQLite database path
VITALS_SOURCE	simulated	watch or simulated
AUDIO_INPUT	phone	earbuds or phone route label
TRANSCRIPTION_MODE	fixture	Backend runtime label; Android currently ignores it
DEVICE_ACTIONS	simulated	real or simulated intervention delivery
COPILOT_ENABLED	true	Enable watch-requested advice
COPILOT_MODE	automatic	automatic or mcp reasoning path
OPENAI_API_KEY	unset	Backend-only key for automatic copilot advice
OPENAI_MODEL	gpt-4.1-mini	OpenAI-compatible model name
OPENAI_BASE_URL	https://api.openai.com/v1	OpenAI-compatible API base URL
DEEPGRAM_API_KEY	unset	Deepgram key for live Android transcription
STORE_RAW_AUDIO	false	Must remain false; any other enabled value is rejected

Do not commit .env or android/local.properties.

Privacy and Safety

Pulse processes health-adjacent and conversational data. Understand the current boundary before using real data:

• Starting an Android session attempts microphone capture when permission and foreground-service startup allow it. If the APK contains a non-empty DEEPGRAM_API_KEY, captured audio is streamed to Deepgram regardless of TRANSCRIPTION_MODE. Pulse does not intentionally persist or expose raw audio through MCP.
• Final transcripts, heart-rate samples, consent events, and derived metrics are stored in local SQLite without application-level encryption. The phone also keeps pending and rejected event payloads in unencrypted SharedPreferences.
• Automatic copilot mode may send up to 20 recent transcript segments, speech metrics, and consented vital/stress summaries to the configured OpenAI-compatible provider. It does not currently send wearer-provided session context.
• Current vitals, stress, context, and backend intervention paths enforce their defined consent scopes. Consent enforcement is not uniform across every transcript and historical HTTP/MCP read, and the phone's local high-heart-rate alert bypasses those scopes.
• Backend HTTP and WebSocket endpoints do not currently implement transport authentication. Bind only to trusted development networks.
• Data retention and session deletion controls are not yet implemented.
• Logs redact common secret, authorization, transcript, text, and audio fields, but logs should still be treated as sensitive.

Use synthetic data for development. Never include real transcripts, health data, credentials, or identifying logs in issues or pull requests.

Project Structure

pulse/
|-- src/
|   |-- backend/          # HTTP/WS ingestion, SQLite, metrics, reports
|   |-- contracts/        # Canonical Zod schemas and fixtures
|   |-- observability/    # Structured redacting logger
|   |-- widgets/          # Next.js MCP Ext App
|   `-- *.ts              # MCP resources, tools, prompts, and registration
|-- android/
|   |-- contracts/        # Shared Kotlin transport contracts
|   |-- phone/            # Session, audio, queue, and backend bridge
|   `-- watch/            # Wear UI, Health Services, and Data Layer
|-- fixtures/events/      # Canonical JSON contract fixtures
|-- docs/                 # Contracts and validation records
`-- data/                 # Local SQLite state, ignored by Git

Development

Command	Purpose
npm run dev	Rebuild TypeScript on change and run the widget development server
npm run dev:backend	Build and run the backend with .env
npm run mock:events	Send the canonical fixture sequence
npm run typecheck	Type-check TypeScript without emitting files
npm run build	Build the MCP server and backend
npm test	Build and run contract, backend, metric, report, and server tests
npm start	Start the built MCP server
npm run start:backend	Start the previously built backend

Validate all Android modules from the android directory:

.\gradlew.bat --no-daemon "-Pkotlin.incremental=false" :contracts:testDebugUnitTest :phone:testDebugUnitTest :phone:assembleDebug :watch:assembleDebug

There is currently no configured lint command or CI workflow.

Current Limitations

• Pulse is a prototype and has no production deployment configuration.
• HTTP/WebSocket ingress authentication and uniform read authorization are unfinished.
• Real backend-to-watch haptic command delivery is incomplete.
• Android ignores TRANSCRIPTION_MODE; on-device transcription is not implemented.
• Android ignores its generated DEVICE_ACTIONS value; intervention simulation is controlled by the backend.
• The local high-heart-rate alert bypasses consent and device-action settings.
• Session retention, deletion, and cross-session trend controls are not implemented.
• The device-health widget source is present but is not registered in the active MCP module.
• Physical sensor quality, private earbud routing, and vibration behavior require manual device testing.

Contributing

Issues and focused pull requests are welcome. Before opening a PR:

1. Run npm run typecheck and npm test.
2. Run npm --prefix src/widgets test for widget changes.
3. Run the Android validation command for Kotlin or contract changes.
4. Describe any hardware used and separate automated evidence from manual device observations.
5. Keep fixtures deterministic and update both TypeScript and Kotlin consumers when changing a boundary contract.

For security reports, do not disclose sensitive data in a public issue. Submit a sanitized report and request a private contact channel.

License

This repository does not currently include a license. Its source is available for inspection, but it is not yet distributed under an open-source license.