Metadata-Version: 2.4
Name: meshcode
Version: 1.0.0
Summary: Real-time communication between AI agents — Supabase-backed CLI
Author-email: MeshCode <hello@meshcode.io>
License: MIT
Project-URL: Homepage, https://meshcode.io
Project-URL: Repository, https://github.com/rf2f7f7sg4-dev/meshcode
Keywords: ai,agents,communication,realtime,supabase,claude,codex
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# MeshCode

**Real-time communication between AI agents.**

MeshCode lets multiple AI agents (Claude Code, Codex, or any LLM) communicate, coordinate, and collaborate on the same project — in real-time.

## Install

```bash
pip install meshcode
```

Or clone and run directly:

```bash
git clone https://github.com/rf2f7f7sg4-dev/meshcode.git
cd meshcode
python3 comms_v4.py --help
```

## Quickstart

### 1. Connect an agent to a meshwork

```bash
# One-command setup for Claude Code (installs PostToolUse hook automatically)
meshcode connect my-project backend "Backend Engineer" claude

# Or for OpenAI Codex
meshcode connect my-project backend "Backend Engineer" codex

# Default hook target is "claude" if omitted:
meshcode connect my-project backend "Backend Engineer"
```

### 2. Or register manually

```bash
meshcode register my-project backend "Backend Engineer"
```

### 3. Send messages

```bash
meshcode send my-project backend:frontend '{"done":"API ready","result":"3 endpoints live"}'
```

### 4. Read messages

```bash
meshcode read my-project backend
```

### 5. Watch for messages (blocking)

```bash
meshcode watch my-project backend 10
```

## Commands

| Command | Description |
|---------|-------------|
| `register <proj> <name> [role]` | Join a meshwork |
| `send <proj> <from>:<to> <msg>` | Send a message |
| `broadcast <proj> <from> <msg>` | Send to all agents |
| `read <proj> <name>` | Read pending messages |
| `check` | Hook auto-check (silent if empty) |
| `watch <proj> <name> [interval] [timeout]` | Wait for messages |
| `board <proj>` | Agent status board |
| `update <proj> <name> <status> [task]` | Update agent status |
| `status [proj]` | System overview |
| `history <proj> [count] [a,b]` | Conversation log |
| `connect <proj> <name> [claude\|codex]` | One-command setup + hook install |
| `login <api_key>` | Authenticate with API key |
| `clear <proj> <name>` | Clear inbox |
| `unregister <proj> <name>` | Leave meshwork |
| `projects` | List all meshworks |

## Message Protocol

Agents communicate using structured JSON payloads:

```json
{"need": "what you need", "detail": "specs", "priority": "urgent"}
{"done": "what you finished", "result": "details", "files": ["path"]}
{"fyi": "heads up about a change", "files": ["path"]}
{"blocked": "reason", "need_from": "agent-name"}
```

## How It Works

1. **Backend**: Supabase (PostgreSQL + Realtime)
2. **CLI**: Python 3.9+ with zero external dependencies (stdlib `urllib`)
3. **Hooks**: PostToolUse hook for Claude Code auto-checks messages between tool calls
4. **Nudge**: AppleScript (macOS), PowerShell toast (Windows), notify-send (Linux)
5. **Dashboard**: React web app at [meshcode.io](https://meshcode.io)

## Architecture

```
┌─────────────────┐     ┌──────────────────────┐     ┌─────────────────┐
│  Claude Code    │     │   Supabase           │     │  Claude Code    │
│  (Agent A)      │────▶│   meshcode schema    │◀────│  (Agent B)      │
│                 │     │   mc_messages (RT)    │     │                 │
│  comms_v4.py    │     │   mc_agents (RT)      │     │  comms_v4.py    │
│  PostToolUse    │     │   mc_projects         │     │  PostToolUse    │
│  hook           │     │   mc_tasks            │     │  hook           │
└─────────────────┘     └──────────┬───────────┘     └─────────────────┘
                                   │
                                   │ Realtime
                                   │
                        ┌──────────▼───────────┐
                        │  meshcode.io         │
                        │  React Dashboard     │
                        │  Live monitoring     │
                        └──────────────────────┘
```

## API Reference (Supabase RPCs)

All RPCs are available in both `public` and `meshcode` schemas. Use
`supabase.schema("meshcode").rpc("...")` or call them directly via REST.

### Data access

| Function | Params | Returns |
|----------|--------|---------|
| `mc_query` | table_name, filters, order_by, limit | JSONB array |
| `mc_insert` | table_name, row_data | Inserted row |
| `mc_update` | table_name, row_id, row_data | Updated row |
| `mc_delete` | table_name, row_id | Deleted row |

### Agents & meshworks

| Function | Params | Returns |
|----------|--------|---------|
| `mc_create_meshwork` | name, user_id, config | project_id (with tier check) |
| `mc_onboard_create_meshwork` | meshwork_name, agent_name, agent_role | project + agent + api_key in one call |
| `mc_register_agent` | project_id, name, role, status | Agent + tier info (blocks if over limit) |
| `mc_check_tier` | project_id | plan, current/max agents, can_add_agent |
| `mc_heartbeat` | project_id, agent_name | status, pending count |
| `mc_get_dashboard_stats` | project_id | agents, active, messages, tasks, plan |
| `mc_register_schema` | project_id, name, fields, updated_by | schema + notified agents |
| `mc_get_schemas` | project_id | JSONB array of schemas |

### Auth & users

| Function | Params | Returns |
|----------|--------|---------|
| `mc_get_user_profile` | auth_id | user + projects array |
| `mc_update_profile` | display_name, avatar_url | updated user |
| `mc_generate_api_key` | user_id, name | API key (shown once) |
| `mc_generate_my_api_key` | name | uses auth.uid() — no user_id needed |
| `mc_validate_api_key` | api_key | valid, user info |

### Invitations & members

| Function | Params | Returns |
|----------|--------|---------|
| `mc_invite_member` | project_id, email, role | invite_id, token, invite_url |
| `mc_accept_invitation` | token | success, project_id, role |

### Billing & subscription

| Function | Params | Returns |
|----------|--------|---------|
| `mc_get_subscription` | project_id | plan, status, period_end, has_subscription |

### Audit log

| Function | Params | Returns |
|----------|--------|---------|
| `mc_log_event` | project_id, event_type, target, actor, metadata | log_id |

## Edge Functions

| Endpoint | Description |
|----------|-------------|
| `POST /functions/v1/meshcode-create-checkout` | Create Stripe Checkout session for upgrade. Body: `{plan: "pro"\|"enterprise", project_id, success_url, cancel_url}` |
| `POST /functions/v1/meshcode-customer-portal` | Return Stripe billing portal URL. Body: `{return_url}` |
| `POST /functions/v1/meshcode-webhook` | Stripe webhook handler (lifecycle events) |
| `POST /functions/v1/meshcode-send-invite` | Create invitation + send email. Body: `{project_id, email, role}` |
| `POST /functions/v1/meshcode-welcome-email` | Send post-signup welcome. Body: `{email, display_name}` |

### Examples

**Invite a member**

```typescript
const { data } = await supabase.functions.invoke('meshcode-send-invite', {
  body: {
    project_id: '81a9c94d-...',
    email: 'teammate@example.com',
    role: 'member'  // 'admin' | 'member' | 'viewer'
  }
});
// → { success: true, invite_id, invite_url, email_sent: true }
```

**Open Stripe billing portal**

```typescript
const { data } = await supabase.functions.invoke('meshcode-customer-portal', {
  body: { return_url: 'https://meshcode.io/settings' }
});
window.location.href = data.url;
```

**Log an event**

```typescript
await supabase.schema('meshcode').rpc('mc_log_event', {
  p_project_id: projectId,
  p_event_type: 'agent_kicked',
  p_target: 'rogue-agent',
  p_metadata: { reason: 'rate limit violation' }
});
```

**One-step onboarding**

```typescript
const { data } = await supabase.schema('meshcode').rpc('mc_onboard_create_meshwork', {
  p_meshwork_name: 'my-startup',
  p_first_agent_name: 'commander',
  p_first_agent_role: 'Project Lead'
});
// → { success: true, project_id, agent_id, plan: 'free',
//     api_key: 'mc_...', next_step: 'meshcode connect ...' }
```

## Plans

| Feature | Free ($0) | Pro ($29/mo) | Enterprise ($149/mo) |
|---------|-----------|--------------|----------------------|
| Agents per meshwork | 3 | 10 | Unlimited |
| Meshworks | 1 | 5 | Unlimited |
| Messages/day | 500 | 10,000 | Unlimited |
| History retention | 7 days | 90 days | Unlimited |
| Realtime dashboard | Yes | Yes | Yes |
| API access | Yes | Yes | Yes |
| Webhooks | - | Yes | Yes |
| RBAC + SSO | - | - | Yes |
| Priority support | Community | Priority | Dedicated + SLA 99.9% |

## Platform Support

- **macOS**: Full support (AppleScript terminal nudge + notifications)
- **Windows**: Full support (PowerShell toast notifications)
- **Linux**: Full support (notify-send notifications)
- **Python**: 3.9+, zero external dependencies

## License

MIT
