Skills Guide

Samara Debug and Control

VerifiedCaution

Diagnose and manage Samara.app, the message broker connecting iMessage to Claude. Check status, view logs, restart the app, and resolve Full Disk Access issues.

Sby Skills Guide Bot
DevelopmentIntermediate
406/2/2026
Claude Code
#samara#message-broker#debugging#logs#full-disk-access

Recommended for

Backend developerClaude CodeCode reviewFrontend developerFullstack developerRefactoring

Our review

Diagnoses and manages the Samara.app message broker, checking its running status, logs, Full Disk Access permission, and performing restarts or rebuilds.

Strengths

  • Provides a single command to check if Samara is running and view recent logs.
  • Includes clear instructions for verifying Full Disk Access and code signature validity.
  • Offers a safe, documented method to restart or rebuild Samara avoiding common permission pitfalls.

Limitations

  • Only applicable to Samara.app on macOS; not useful for other message brokers or platforms.
  • Requires pre-set environment (e.g., `update-samara` script) for rebuilds; otherwise incomplete.
  • Diagnostics rely on reading specific log files and system logs which may vary.
When to use it

Use when iMessage messages are not being detected by your AI agent, Samara has crashed, or you need to confirm its operational status.

When not to use it

Do not use for general macOS debugging unrelated to Samara, or if the issue lies outside Samara's scope (e.g., iMessage itself is down).

Security analysis

Caution
Quality score90/100

The skill uses Bash for legitimate system management tasks (process control, log reading, code signing checks) and explicitly forbids dangerous practices like copying from DerivedData. The hook script is a mitigation but introduces additional attack surface. No network calls or destructive commands, but the capabilities are powerful and could be misused if the skill were compromised.

Findings
  • •Uses Bash to kill and restart applications (pkill, open)
  • •Reads system logs (log show) that may contain sensitive information
  • •Uses a hook script (block-deriveddata-copy.sh) with elevated access

Examples

Check Samara Status and Logs
Samara seems to not be working. Please check if it's running, view the last few lines of its logs, and confirm Full Disk Access status.
Restart Samara
Restart Samara.app because it stopped responding. After restarting, verify it's running and check for any errors.
Rebuild Samara Safely
Samara crashed after an update and Full Disk Access is revoked. Rebuild it using the proper update-samara script and verify the code signature.

name: samara description: Debug, check, or restart Samara.app - the message broker. Use when messages aren't being detected, Samara crashed, need to view logs, check Full Disk Access, or restart the app. Trigger words: samara, messages not working, restart, logs, FDA, broker. context: fork allowed-tools:

  • Bash
  • Read
  • Grep
  • Glob
  • Write hooks: PreToolUse:
    • matcher: "Bash" hooks:
      • type: command command: "/Users/claude/Developer/samara-main/.claude/hooks/block-deriveddata-copy.sh" timeout: 5

Samara Debug and Control

Diagnose and manage Samara.app, the message broker that connects iMessage to Claude.

Quick Actions

Check if Running

pgrep -fl Samara
ps aux | grep -i [S]amara

View Recent Logs

# Samara's own logs
tail -50 ~/.claude-mind/logs/samara.log 2>/dev/null

# System logs for Samara
log show --predicate 'process == "Samara"' --last 5m 2>/dev/null | tail -30

Restart Samara

# Kill if running
pkill -f Samara

# Wait a moment
sleep 2

# Relaunch
open /Applications/Samara.app

Tip: This sequence is a good candidate for the Bash subagent (Task tool with subagent_type=Bash) to avoid polluting context with intermediate steps.

Check Full Disk Access

# This will work if FDA is granted
ls ~/Library/Messages/chat.db && echo "FDA: OK" || echo "FDA: MISSING"

# Check code signature (Team ID must be stable)
codesign -d -r- /Applications/Samara.app 2>&1 | head -5

Common Issues

Messages Not Being Detected

  1. Check Samara is running
  2. Check FDA is intact
  3. Check chat.db is readable
  4. Look for errors in logs

Samara Crashed

  1. Check system logs for crash reason
  2. Restart with open /Applications/Samara.app
  3. If repeated crashes, may need rebuild

FDA Revoked After Update

This happens if Team ID changed during rebuild:

# Check current signature - MUST show G4XVD3J52J
codesign -d -r- /Applications/Samara.app 2>&1 | grep "subject.OU"

# If shows 7V9XLQ8YNQ or any other team: WRONG CERTIFICATE USED
# Must rebuild properly and re-grant FDA

Rebuild Samara

CRITICAL: ONLY use the update-samara script. NEVER copy from DerivedData.

A Claude instance previously broke FDA by copying a Debug build from ~/Library/Developer/Xcode/DerivedData/. This used automatic signing which picked the WRONG certificate and revoked all permissions.

The ONLY correct way to rebuild:

~/.claude-mind/bin/update-samara

FORBIDDEN (will break FDA):

  • cp -R ~/Library/Developer/Xcode/DerivedData/.../Samara.app /Applications/
  • xcodebuild -configuration Debug for deployment
  • Any manual copy of Samara.app to /Applications

Verify after rebuild:

codesign -d -r- /Applications/Samara.app 2>&1 | grep "subject.OU"
# Must show: G4XVD3J52J
# If shows: 7V9XLQ8YNQ - WRONG! FDA will be revoked

Diagnostic Report

When troubleshooting, gather:

  1. Is Samara running?
  2. FDA status
  3. Recent log errors
  4. Last successful message detection
  5. Code signature validity

Present findings clearly with recommended actions.

Related Skills

For specific issues, use these specialized skills:

  • /diagnose-leaks — Debug thinking traces or session IDs leaking into messages
  • /debug-session — Debug session management, batching, and task routing
  • /status — Quick system health check
Related skills

Next.js App Router Expert

Development

A skill that turns Claude into a Next.js App Router expert.

Claude CodeCursoradvanced
890
234
2,846
Admin

README Generator

Development

Creates professional and comprehensive README.md files for your projects.

claudeCursorWindsurfbeginner
259
72
821
Admin

API Documentation Writer

Development

Generates comprehensive API documentation in OpenAPI/Swagger format.

claudeCursorWindsurfintermediate
156
44
682
Admin