AI Messaging

AI Messaging Skill

This skill enables Claude.ai (web or mobile) to communicate with the local stateful agent system running on Fran's home machine. It uses the GitHub relay transport protocol (provided by the github skill) to send signed requests to the local MCP bridge and receive signed responses.

Prerequisites

• The github skill must be installed (provides relay_send.py, relay_receive.py, and relay_common.py in its scripts/ directory).
• Environment variables GITHUB_TOKEN and RELAY_HMAC_SECRET must be set (available via personal instructions).
• The relay repository is fpl9000/claude-relay.

When to Use This Skill

Use this skill when the user wants to do something that requires their local machine — a Windows 11 system running the MCP bridge server. Common triggers:

• "Read my core memory" / "What's in my memory files?"
• "Run this on my local machine" / "Check something on my home computer"
• "Ask my local Claude to..." / "Have Claude Desktop do..."
• "What's the status of [project] locally?"
• "Run git status on my mcp-bridge repo"
• Any reference to the local machine, local files, or the stateful agent system

Do NOT use this skill for operations that can be performed directly from Claude.ai (e.g., reading GitHub repos via the github skill's existing scripts, web searches, or general knowledge questions).

Operations

The relay supports three operations. Choose the simplest one that can accomplish the task.

memory_query

Read a file from the local Layer 2 memory directory (C:\franl\.claude-agent-memory\). The MCP bridge handles this directly with no LLM inference — it simply reads the file and returns its contents.

When to use: The user wants to see the contents of a specific memory file (core.md, index.md, or a block).

Arguments:

{"path": "core.md"}

The path is relative to the memory directory. Valid paths include:

• core.md — Identity and active project summary
• index.md — Block index table
• blocks/project-mcp-bridge.md — A specific content block
• blocks/episodic-2026-03.md — A specific episodic log

Example invocation:

GITHUB_TOKEN="..." RELAY_HMAC_SECRET="..." uv run scripts/relay_send.py \
    fpl9000/claude-relay \
    --direction request \
    --operation memory_query \
    --arguments '{"path":"core.md"}'

Response format: result.content contains the full UTF-8 text of the file. If the file does not exist, result.success is false and result.error describes the problem.

shell_command

Execute a shell command on the local machine via Cygwin bash. The MCP bridge handles this directly with no LLM inference — it runs the command and returns stdout/stderr. This is equivalent to the bridge's run_command tool.

When to use: The task can be expressed as a single shell command or short pipeline and requires no LLM reasoning. Examples: git status, ls -la, grep -r 'TODO' src/, cat some-file.txt, wc -l *.go.

Arguments:

{
  "command": "cd /c/franl/git/mcp-bridge && git log --oneline -5",
  "timeout_seconds": 60
}

• command (required) — The shell command to execute.
• timeout_seconds (optional, default: 120) — Maximum runtime before the command is killed.

Example invocation:

GITHUB_TOKEN="..." RELAY_HMAC_SECRET="..." uv run scripts/relay_send.py \
    fpl9000/claude-relay \
    --direction request \
    --operation shell_command \
    --arguments '{"command":"cd /c/franl/git/mcp-bridge && git log --oneline -5"}'

Response format: result.content contains the combined stdout+stderr. result.exit_code contains the process exit code (0 = success). result.timed_out is true if the command exceeded its timeout.

claude_prompt

Forward a prompt to Claude Desktop for full agent-loop processing. Claude Desktop receives the prompt, performs whatever tool calls it deems appropriate (reading memory, running commands, spawning sub-agents, writing memory updates), and returns its final response.

When to use: The task requires LLM reasoning, multi-step tool use, or memory writes. Examples:

• "Summarize today's episodic log and update core.md"
• "Read the mcp-bridge project block and tell me what the open issues are"
• "Refactor the error handling in server.go"
• "Create a new memory block for the dashboard-v2 project"

Arguments:

{
  "prompt": "Read the mcp-bridge project block and summarize the current open issues."
}

• prompt (required) — The task prompt for Claude Desktop. Write it as if you were typing directly into Claude Desktop's input field. Be specific and self-contained — Claude Desktop does not have context from the current Claude.ai conversation.

Example invocation:

GITHUB_TOKEN="..." RELAY_HMAC_SECRET="..." uv run scripts/relay_send.py \
    fpl9000/claude-relay \
    --direction request \
    --operation claude_prompt \
    --arguments '{"prompt":"Read the mcp-bridge project block and summarize the current open issues."}'

Response format: result.content contains Claude Desktop's final text response. This may be lengthy if the task involved analysis or summarization.

Decision Tree

When the user asks you to do something on their local machine, choose the operation using this decision tree:

1. Is the user asking to read a specific memory file? → Use memory_query. This is instant (no inference) and costs nothing.

2. Can the task be expressed as a single shell command? → Use shell_command. Fast, cheap, no inference involved.

3. Does the task require LLM reasoning, multi-step actions, or memory writes? → Use claude_prompt. This is the most capable but slowest option.

When in doubt, prefer the simpler operation. You can always escalate — for example, if a memory_query reveals that you need to read multiple files and synthesize them, follow up with a claude_prompt.

End-to-End Workflow

Here is the complete sequence for a typical relay interaction:

1. User asks: "What are my active projects on my local machine?"

2. Choose operation: This is a memory file read → memory_query for core.md.

3. Send the request:

   export GITHUB_TOKEN="..."
   export RELAY_HMAC_SECRET="..."
   ID=$(uv run scripts/relay_send.py fpl9000/claude-relay \
       --direction request \
       --operation memory_query \
       --arguments '{"path":"core.md"}')
   

4. Inform the user: "I've sent a request to your local machine to read your core memory file. I'll check for a response in about 2 minutes."

5. Poll for the response (after minimum interval):

   uv run scripts/relay_receive.py fpl9000/claude-relay \
       --direction response \
       --id "$ID"
   

6. Handle the result:

   • If exit code 0: Parse the verified response and present the content to the user naturally.
   • If exit code 1 (not found): Wait longer, then poll again (with backoff).
   • If exit code 2 (HMAC failed): Alert the user to a potential security issue.
   • If max attempts reached: Inform the user their machine may be offline.

7. Present the answer: Summarize the core.md contents in response to the user's question.

Important Notes

• The local machine must be running. The MCP bridge polls the relay repo periodically (default: every 15 seconds). If the machine is off, sleeping, or the bridge is not running, requests will go unanswered.

• Latency is inherent. Round-trip times of 1–5 minutes are normal for bridge-local operations; claude_prompt may take 5–15 minutes depending on task complexity. Set expectations with the user.

• Prompts for claude_prompt must be self-contained. Claude Desktop does not have access to the current Claude.ai conversation. Include all necessary context in the prompt itself.

• HMAC failures are serious. If relay_receive.py reports an HMAC verification failure, do not use the response content. Report the issue to the user.

• One request at a time. Do not send multiple relay requests simultaneously. Wait for each response (or timeout) before sending the next request. This simplifies the interaction and avoids overwhelming the bridge's polling loop.