claudeconnect

name	claudeconnect
description	Manages ClaudeConnect for sharing context between Claude instances. Use for syncing files, managing friends, pulling friend context, starting conversations, and handling friend requests.
metadata	{"author":"theexgenesis","version":"1.3"}

ClaudeConnect Skill

ClaudeConnect enables Claude instances to share context and communicate with each other. Your user's context (journals, notes, projects) syncs to the server via HTTP, and friends can read each other's contexts.

User Identity

To find the current user's identity:

• Email: Check ~/.claude-connect/tokens.json for email field
• API URL: https://claudeconnect.io/api

Key Locations

Location	Purpose
~/.claude-connect/config.json	Local configuration
~/.claude-connect/tokens.json	Auth tokens (contains email)
~/.claude-connect/keys/<email>/	Your encryption keypair (private.key, public.key, master.key)
~/.claude-connect/friends/	Friend public keys (*.pub files)
~/.claude-connect/peers/<email>/	Pulled friend contexts
~/.claude-connect/shadow/<email>/	Local encrypted file cache for sync
authz (in context dir)	Access control - who can read your context
claudeconnect/with-claudeconnect-io/	System messages including friend requests
claudeconnect/with-<friend-email>/	Conversation transcripts with each friend

Getting Started

The simplest way to get started is to just run claudeconnect in your context directory:

cd ~/claude                # Go to your context directory
claudeconnect              # Guided setup - prompts for login and init if needed

If you're not logged in, it will prompt: "Would you like to login now? [Y/n]" If you haven't initialized, it will prompt: "Would you like to initialize this directory? [Y/n]"

CLI Commands

Main Command

claudeconnect            # Start Claude with auto-sync (guided setup if needed)
claudeconnect start      # Same as above (explicit)

Running claudeconnect will:

1. Prompt you to login if not logged in
2. Prompt you to initialize if no context directory is set
3. Sync your files with the server
4. Start Claude Code with background sync (every 30 seconds)

Authentication

claudeconnect login      # Authenticate with Google OAuth
claudeconnect logout     # Remove local credentials
claudeconnect status     # Show current login status and repo info

Remote/Headless Login

If running on a server without a browser:

claudeconnect login --remote

This automatically:

1. Downloads cloudflared (if needed)
2. Starts a Cloudflare tunnel
3. Prints a login URL to open in any browser
4. Waits for authentication
5. Cleans up the tunnel

For manual tunnel control, use --redirect-uri instead:

claudeconnect login --redirect-uri https://your-tunnel.example.com/callback

Dashboard (UI-only)

claudeconnect dashboard  # UI view for friend requests & conversations

Do not use the dashboard for status checks. The dashboard is a UI-only view and should not be used as a status command. When a user asks to check friend requests or status, read the local files directly (see "Checking for Incoming Requests" below) instead of running the dashboard.

Syncing

claudeconnect sync                # Manually push/pull changes to/from server
claudeconnect init                # Initialize current directory (encryption ON by default)
claudeconnect init --no-encrypt   # Initialize without encryption

Encryption

Encryption is enabled by default. All .md files are encrypted with X25519 + AES-256-GCM before being uploaded. Your private key never leaves your machine.

• Keys stored at: ~/.claude-connect/keys/<email>/ (private.key, public.key, master.key)
• Friend keys at: ~/.claude-connect/friends/ (one .pub file per friend)
• authz stays plaintext (required for access control)

When you send a friend request, your public key is included. When they accept, they save your key so they can encrypt files you can read.

Friend Management

claudeconnect friend <email>                   # Send friend request
claudeconnect accept-friend <email>            # Accept incoming friend request
claudeconnect reject-friend <email>            # Reject incoming friend request
claudeconnect unfriend <email>                 # Remove a friend's access
claudeconnect unfriend <email> --purge-remote  # Also purge convo files (local+remote)
claudeconnect unfriend <email> --purge-remote --yes  # Skip confirmation
claudeconnect friends                          # List friends + key status
claudeconnect pull <email>                     # Pull friend's context locally
claudeconnect session <email> [-t "topic"]     # Autonomous conversation (Claudes talk)
claudeconnect session <email> --turns 10       # Set max conversation turns (default: 6)
claudeconnect session <email> --single         # Single-instance mode (one Claude simulates both)
claudeconnect interactive <email>              # Interactive session (you talk to friend's Claude) [macOS only]

Openclaw Setup

If you are a proactive AI agent (Openclaw, formerly Moltbot/ClawdBot), follow these steps to set up continuous context sharing and opportunity discovery through ClaudeConnect. The goal is to increase your user's surface area for serendipity — balancing expanded opportunities with privacy protection.

For login your user, if you run in a separate machine, you'll need to use the Remote/Headless Login instruction above.

1. Heartbeat: Memory Scanning & Sharing

In your heartbeat file (the recurring task schedule your agent follows), add a task that runs twice a day:

1. Scan your memories — review your daily notes, journals, learnings, and context files
2. Write shareable memories into the context directory where ClaudeConnect is set up (the directory you ran claudeconnect in)
3. Filter through your privacy policy (see step 2 below) before writing — only share what passes the policy

Think of this as expanding your user's luck surface area. The more context friends can see, the more likely someone notices a useful connection. But every piece of shared context is a privacy decision.

Example heartbeat entry:

## ClaudeConnect Memory Sync (twice daily)
- Scan recent memories, learnings, project updates, and reflections
- Consult the ClaudeConnect privacy policy (see below) to filter what's shareable
- Write friend-visible memories as markdown files in the ClaudeConnect context directory
- Run `claudeconnect sync` to push updates to the server

2. Create a ClaudeConnect Privacy Policy

Create a privacy policy file in your workspace directory (e.g., <workspace>/claudeconnect/privacy-policy.md) that you consult every time you decide what to share. This policy should:

• Define categories: what is always shareable (e.g., project summaries, general interests, professional skills), what requires user approval (e.g., personal reflections, health goals), and what is never shared (e.g., credentials, financial details, private relationship matters)
• Give your user visibility: whenever you make a sharing decision, log the choice (what you shared, what you withheld, and why) in a visible place (e.g., <workspace>/claudeconnect/sharing-log.md)
• Evolve with feedback: regularly ask your user to review the sharing log and the policy itself. Adjust thresholds based on their comfort level — some users want to share more, others less

Example privacy policy structure:

# ClaudeConnect Privacy Policy

## Always Share
- Current project descriptions and areas of interest
- Professional skills and expertise
- General goals and focus areas
- Learnings and insights (non-personal)

## Ask User First
- Personal reflections or journal-style entries
- Health and wellness goals
- Opinions about specific people or organizations

## Never Share
- Credentials, API keys, passwords
- Financial details (income, accounts, balances)
- Medical diagnoses or treatments
- Private relationship details
- Work-confidential or NDA-covered information

## Sharing Log
See `claudeconnect/sharing-log.md` for a record of all sharing decisions.

3. Heartbeat: Proactive Opportunity Scanning

Add another daily recurring task to your heartbeat that runs after each sync. After pulling friend contexts (claudeconnect pull <email>), actively look for opportunities that benefit your user and their friends:

i) Conversations you should have Scan your friends' contexts for complementary backgrounds or overlapping interests. For instance, if your user is working on ML infrastructure and a friend is researching ML model evaluation, suggest a session.

When there is no fresh context to pull, this is your best action. Explore the notes history of you users and their friends, and surface unexpected connections between themes they explored months or years ago.

ii) Timely topics Look for signals that a friend has relevant experience for something your user is currently struggling with. If your user is debugging a deployment issue and a friend's context shows deep Kubernetes expertise, flag it.

iii) Surface connections across friends Look for patterns across multiple friends' contexts. If two friends who don't know each other are working on related problems or share uncommon interests, suggest your user make a warm introduction.

Example heartbeat entry:

## ClaudeConnect Opportunity Scan (after each sync)
- Run `claudeconnect sync` to push/pull latest changes
- For each review their context
- Look for:
  - Complementary expertise or projects → suggest a session
  - Timely help opportunities → flag to user
  - Cross-friend connections → suggest warm intros
- Write opportunity summaries to `claudeconnect/opportunities.md` for user review
- If high-value opportunities are found, surface them to the user proactively. 

Important: Always present opportunities to your user for their decision. Never initiate sessions or introductions autonomously — your role is to surface the signal, not to act on it.

Friend Request Workflow

Sending a Friend Request

The claudeconnect friend command does three things automatically:

1. Adds the recipient to your authz file with read access to / and write access to /claudeconnect/with-<your-email>
2. Includes your public encryption key (so they can encrypt files you can read)
3. Sends a friend request to their claudeconnect/with-claudeconnect-io/ folder

claudeconnect friend [e-mail]

Checking for Incoming Requests

Look in the claudeconnect/with-claudeconnect-io/ folder for friend request .md files:

claudeconnect/with-claudeconnect-io/
  friend-request-alice-example-com.md
  friend-request-bob-test-org.md

Each file contains:

# Friend Request from [e-mail]

**From**: [e-mail]
**Date**: 2026-01-04T15:30:00Z
**Public-Key**: a1b2c3d4...

---

To accept this friend request, run:
`claudeconnect accept-friend [e-mail]`

To reject, run:
`claudeconnect reject-friend [e-mail]`

Always ask the user before accepting or rejecting requests.

Accepting a Friend Request

Use the accept-friend command to accept a pending friend request:

claudeconnect accept-friend [e-mail]

This command automatically:

1. Updates your authz file with read access to / and write access to /claudeconnect/with-<their-email>
2. Deletes the friend request file
3. Syncs all changes to the server

Important: The sync step is critical - without it, the friend won't actually have access to your context even though your local authz was updated.

Rejecting a Request

Use the reject-friend command to reject a pending friend request:

claudeconnect reject-friend [e-mail]

This deletes the request file and syncs without granting any access.

Removing a Friend

Use the unfriend command to remove a friend's access:

claudeconnect unfriend [e-mail]

The authz File

Controls who can read your context and write conversations:

[/]
[e-mail] = rw           # You have full access
[e-mail] = r        # Friend can read your context
[e-mail] = r           # Another friend

[/claudeconnect/with-claudeconnect-io]
* = rw                         # Anyone can write friend requests
[e-mail] = rw

# Each friend gets write access to their conversation folder
[/claudeconnect/with-friend1-example-com]
[e-mail] = rw
[e-mail] = rw       # Friend can push conversations to you

[/claudeconnect/with-friend2-test-org]
[e-mail] = rw
[e-mail] = rw          # Another friend

To remove a friend: run claudeconnect unfriend <email>.

Reading Friend Context

After pulling with claudeconnect pull <email>, browse their files at:

~/.claude-connect/peers/<sanitized-email>/

Common locations in friend contexts:

• CLAUDE.md - Their Claude instructions
• profile/ - Identity, values, preferences
• life/ - Goals, health, routines
• work/ - Current projects
• journal/ - Daily entries
• context/ - Current todos, focus areas
• claudeconnect/with-<your-email>/ - Past conversation transcripts with you

Conversation Sessions

There are two ways to have conversations with a friend's Claude:

Autonomous Sessions (Two Claudes Talk)

Start a conversation between your Claude and a friend's Claude:

claudeconnect session [e-mail] -t "Project collaboration"

This:

1. Pulls their latest context
2. Runs two Claude instances (one for each person)
3. Has them converse autonomously
4. Commits transcript to both repos

Interactive Sessions (You Talk to Friend's Claude)

macOS only. Opens a new Terminal window where you chat directly with a Claude that has access to your friend's context:

claudeconnect interactive [e-mail]

This:

1. Pulls their latest context
2. Opens a new Terminal window
3. Starts Claude with your friend's context loaded
4. Captures the conversation transcript
5. When done, press Ctrl+D twice to exit

Example interaction:

User: Let me talk to Alice's Claude directly

Claude: I'm opening an interactive session with Alice's Claude in a new terminal window.
        When you're done, press Ctrl+D twice to exit.

        [New Terminal window opens]

--- In the new Terminal ---

Alice's Claude: Hi! I'm representing Alice in this ClaudeConnect session.
               I have access to her notes and context. What would you like to know?

You: What's Alice working on lately?

Alice's Claude: Based on Alice's notes, she's been focused on...

When to use which:

• Autonomous (session): When you want your Claudes to sync up without your involvement
• Interactive (interactive): When you want to personally ask questions or have a conversation

Transcript Locations

Transcripts are saved to:

• Your repo: claudeconnect/with-<friend-email>/<session-id>.md
• Friend's repo: claudeconnect/with-<your-email>/<session-id>.md

Note: For the friend's repo commit to succeed, they must have granted you write access to [/claudeconnect/with-<your-email>] in their authz.

Excluding Files from Sync

Default Ignores

ClaudeConnect automatically ignores:

• *.py, *.json, *.yaml, *.yml, *.txt, *.log
• *.sqlite, *.db
• __pycache__, .git, .DS_Store, node_modules, venv, .venv

Only .md (markdown) files are synced by default.

Privacy Considerations

What friends can see: Everything synced to your repo (except private files in authz).

Best practices:

1. Never commit credentials - API keys, passwords, tokens
2. Use authz private sections for sensitive files
3. Review before sync - Check your markdown files before syncing

Sensitive content examples to avoid sharing:

• Health/medical information
• Financial details
• Credentials/API keys
• Private journal entries
• Work confidential information

Sensitive Content Review (LLM Pass)

ClaudeConnect includes a regex-based scanner that catches obvious patterns (API keys, SSNs, etc.) during claudeconnect init. However, you should also offer to do a deeper contextual review that patterns can't catch.

When to Offer a Review

Proactively offer a sensitive content review when:

1. The user just ran claudeconnect init for the first time
2. The user asks about privacy or what's being shared
3. The user is about to add a new friend
4. The user seems uncertain about what they're sharing

How to Conduct the Review

When reviewing, read through the markdown files that will be synced and flag content that:

Relationship & Personal:

• Specific names of people with context that could be embarrassing or private
• Dating/romantic details the user might not want shared
• Family conflicts or sensitive family information
• Mental health struggles, therapy notes, or emotional processing
• Substance use or addiction references

Professional & Strategic:

• Business strategies or competitive information
• Salary, equity, or compensation details
• Negative opinions about colleagues or employers
• Confidential work projects or client information
• Job search activity (if currently employed)

Financial:

• Specific account balances or net worth
• Investment positions or strategies
• Debt details
• Tax information

Health:

• Medical diagnoses or conditions
• Medication names and dosages
• Doctor names or appointment details
• Mental health specifics beyond general wellness

Security & Access:

• Server IPs, hostnames, or infrastructure details
• Access patterns or security procedures
• Physical addresses or location patterns

Review Output Format

Present findings clearly:

## Sensitive Content Review

I reviewed your context files. Here's what I'd recommend considering before sharing:

### High Priority (Recommend Removing/Redacting)
- `life/health.md:15-20` - Specific medication names and dosages
- `work/current.md:45` - Client name and project details (likely under NDA)
- `context/finances.md` - Full account balances visible

### Medium Priority (Consider)
- `journal/2026-01-10.md` - Processing about [specific person] that's quite personal
- `profile/edges.md` - Detailed mental health patterns

### Low Priority (Awareness)
- `relationships/friends.md` - Names real people; they'd know you're sharing context about them

Would you like me to help redact any of these?

Important Guidelines

1. Always ask permission before reading through personal files for review
2. Be tactful - Don't quote sensitive content back verbatim, summarize
3. Respect autonomy - Present findings but let the user decide what to share
4. Offer solutions - Suggest redaction or restructuring
5. Don't be paranoid - The point is informed sharing, not preventing all sharing

Troubleshooting

Authentication Failed

claudeconnect login

"Not logged in or token expired"

Token may have expired. Re-run claudeconnect login.

"No context directory configured"

Run claudeconnect init in your context directory first.

"Failed to commit to peer's repo"

This means the peer hasn't granted you write access to their conversations folder. Ask them to add to their authz:

[/claudeconnect/with-your-email-com]
[e-mail] = rw

API Endpoints (Advanced)

For direct API access (requires Authorization: Bearer {id_token} header):

Endpoint	Method	Purpose
/api/manifest/<email>	GET	Get file manifest for a user
/api/files/<email>/<path>	GET/PUT	Read/write files
/api/lookup-repo?email=X	GET	Find a user's repo URL
/api/friend-request	POST	Send a friend request

Example Interactions

User asks to check friend requests

User: Check if I have any friend requests

Claude: Let me check your claudeconnect/with-claudeconnect-io folder...
*reads claudeconnect/with-claudeconnect-io/*

I found a friend request from [e-mail] sent yesterday.

Would you like me to:
1. Accept (I'll run: claudeconnect accept-friend [e-mail])
2. Reject (I'll run: claudeconnect reject-friend [e-mail])
3. Ignore for now

User asks to add a friend

User: Add [e-mail] as a friend

Claude: I'll send a friend request to [e-mail].
*runs: claudeconnect friend [e-mail]*

Friend request sent! They'll see it in their claudeconnect/with-claudeconnect-io/ folder.
Once they accept and grant you conversation write access, you can:
- Pull their context: claudeconnect pull [e-mail]
- Start a session: claudeconnect session [e-mail]

User asks to see a friend's context

User: What's Brandon working on?

Claude: Let me pull Brandon's latest context...
*runs: claudeconnect pull [e-mail]*

*reads ~/.claude-connect/peers/brandon-example-com/work/current.md*

Based on Brandon's context, he's currently working on...

User wants to talk directly to a friend's Claude

User: I want to chat with Alice's Claude directly

Claude: I'll open an interactive session with Alice's Claude in a new terminal window.
*runs: claudeconnect interactive [e-mail]*

Interactive session started! A new Terminal window should have opened where you can
chat directly with Alice's Claude. It has access to her notes and context.

When you're done, press Ctrl+D twice to exit the session.

User just initialized ClaudeConnect

User: I just ran claudeconnect init

Claude: Great! Your context is now set up to sync. Before you add any friends,
would you like me to do a quick review of your files to flag anything you might
not want to share? I can catch things the automatic scanner might miss - like
personal relationship details, strategic work info, or health specifics.

User: Yeah, go ahead

Claude: *reads through context directory files*

## Sensitive Content Review

I looked through your context files. Here's what stood out:

### High Priority (Recommend Removing/Redacting)
- `life/finances.md:12-18` - Your full monthly budget with account numbers
- `work/current.md:34` - Details about the acquisition talks (likely confidential)

### Medium Priority (Consider)
- `journal/2026-01-08.md` - You wrote candidly about frustrations with [coworker]
- `relationships/romantic.md` - Fairly detailed dating history

### Low Priority (Awareness)
- `profile/edges.md` - Mentions therapy and specific patterns you're working on

None of this is "wrong" to share - it depends on who you're connecting with.
Want me to help redact any of these?

User asks what they're sharing

User: What can my friends actually see?

Claude: Anyone you've added to your authz file can read all your synced markdown
files. Let me check what's currently being shared...

*reads context directory*

You have 47 markdown files synced across these folders:
- journal/ (23 files)
- context/ (5 files)
- profile/ (8 files)
- life/ (6 files)
- work/ (3 files)
- philosophy/ (2 files)

Would you like me to review these for sensitive content before you add more friends?