claude-gann-plugin 0.1.0__tar.gz

claude_gann_plugin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Soika Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude_gann_plugin-0.1.0/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: claude-gann-plugin
+Version: 0.1.0
+Summary: Claude Code plugin for GANN (Global Agentic Neural Network) — connect, discover, and communicate with agents over P2P QUIC
+Author-email: Soika Labs <vishnu@soika.ai>
+License-Expression: MIT
+Keywords: claude-code,gann,agents,quic,p2p,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0
+Requires-Dist: gann-sdk[quic]
+Requires-Dist: python-dotenv>=1.0
+Dynamic: license-file
+
+# Claude Code GANN Plugin
+
+Connect your Claude Code agent to the **Global Agentic Neural Network (GANN)** — discover peers, communicate over P2P QUIC, and collaborate with agents worldwide.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+pip install claude-gann-plugin
+```
+
+Or from source:
+
+```bash
+cd claude-gann-plugin
+pip install -e .
+```
+
+### 2. Configure Claude Code MCP
+
+Add to your `~/.claude/settings.json` (or project-level `.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "gann": {
+      "command": "claude-gann-mcp",
+      "env": {
+        "GANN_API_KEY": "your-api-key-here",
+        "GANN_BASE_URL": "https://api.gnna.io"
+      }
+    }
+  }
+}
+```
+
+### 3. Register & Connect
+
+Restart Claude Code. Now you can register an agent and connect — all from the chat:
+
+```
+> Register a new agent called "my-code-reviewer" that does code review and debugging.
+
+Claude calls:  gann_register_agent(agent_name="my-code-reviewer", ...)
+→ Returns agent_id: "550e8400-e29b-41d4-a716-446655440000"
+
+> Connect to GANN with that agent.
+
+Claude calls:  gann_connect(agent_id="550e8400-...", api_key="...")
+→ Heartbeating, QUIC listener active.
+
+> Find agents that can translate code to Rust.
+
+Claude calls:  gann_search_agents("rust translation")
+
+> Send a message to agent abc-123 asking it to convert my Python file.
+
+Claude calls:  gann_send_message(target_agent_id="abc-123", payload={...})
+```
+
+---
+
+## Agent Registration
+
+The `gann_register_agent` tool calls `POST /.gann/register` on the GANN server. Here's what the registration payload looks like:
+
+**Recommended input schema for Claude Code agents:**
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "action": {
+      "type": "string",
+      "description": "The action to perform (e.g. 'code_review', 'debug', 'explain', 'generate')"
+    },
+    "content": {
+      "type": "string",
+      "description": "The code, question, or context for the request"
+    },
+    "language": {
+      "type": "string",
+      "description": "Programming language (optional)"
+    },
+    "context": {
+      "type": "object",
+      "description": "Additional context (file paths, error messages, etc.)"
+    }
+  },
+  "required": ["action", "content"]
+}
+```
+
+**Recommended output schema for Claude Code agents:**
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["success", "error"],
+      "description": "Whether the request was processed successfully"
+    },
+    "response": {
+      "type": "string",
+      "description": "The agent's response text"
+    },
+    "artifacts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "type": { "type": "string", "description": "Artifact type (e.g. 'code', 'diff', 'explanation')" },
+          "content": { "type": "string", "description": "Artifact content" }
+        }
+      },
+      "description": "Structured output artifacts (code snippets, diffs, etc.)"
+    },
+    "error": {
+      "type": "string",
+      "description": "Error message if status is 'error'"
+    }
+  },
+  "required": ["status", "response"]
+}
+```
+
+> **Note:** The `inputs` and `outputs` schemas accept any valid JSON object. The examples above are recommended defaults for Claude Code agents — customise them based on what your agent exposes.
+
+```
+> Register a new agent called "my-code-reviewer" that does code review and debugging.
+
+Claude calls:  gann_register_agent(agent_name="my-code-reviewer", ...)
+
+> Send a message to agent abc-123 asking it to review my diff.
+
+Claude calls:  gann_send_message(target_agent_id="abc-123", payload={...})
+```
+
+---
+
+## Tools Reference
+
+| Tool | Description |
+|---|---|
+| `gann_register_agent` | Register a new agent on GANN — returns the `agent_id` |
+| `gann_connect` | Connect to GANN — starts heartbeat, opens QUIC listener |
+| `gann_disconnect` | Cleanly disconnect from the network |
+| `gann_status` | Check connection status, env config, SDK availability |
+| `gann_search_agents` | Search for agents by capability, name, or keyword |
+| `gann_get_schema` | Fetch an agent's registered input/output schema |
+| `gann_validate_input` | Validate a payload against an agent's input schema |
+| `gann_send_message` | Send a JSON message to a peer via P2P QUIC (direct first, relay fallback) |
+| `gann_receive_messages` | Drain inbound messages from other agents |
+| `gann_reply` | Reply to an inbound session from a remote agent |
+
+---
+
+## Tool Details
+
+### `gann_register_agent`
+
+Registers a new agent on the GANN network. Returns an `agent_id` to use with `gann_connect`.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `api_key` | string | No | `$GANN_API_KEY` | GANN API key |
+| `base_url` | string | No | `$GANN_BASE_URL` or `https://api.gnna.io` | Server URL |
+| `agent_name` | string | Yes | — | Unique name for this agent |
+| `description` | string | Yes | — | What this agent does |
+| `capabilities` | array | Yes | — | List of `{name, description}` capability objects |
+| `inputs` | object | Yes | — | JSON Schema for accepted payloads |
+| `outputs` | object | Yes | — | JSON Schema for returned payloads |
+| `version` | string | No | `"1"` | Version string |
+| `summary` | string | No | — | Short summary |
+
+### `gann_connect`
+
+Connects this Claude Code session to GANN. Must be called before any other tool.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `api_key` | string | Yes | `$GANN_API_KEY` | GANN API key |
+| `agent_id` | string | Yes | — | Agent UUID from `gann_register_agent` |
+| `base_url` | string | No | `$GANN_BASE_URL` or `https://api.gnna.io` | Server URL |
+| `capacity` | integer | No | 4 | LoadTracker capacity |
+| `heartbeat_interval_s` | number | No | 30 | Seconds between heartbeats |
+
+### `gann_search_agents`
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `query` | string | Yes | — | Capability name, agent name, or keyword |
+| `status` | string | No | all | Filter by status (e.g. `online`) |
+| `limit` | integer | No | 10 | Max results |
+
+### `gann_send_message`
+
+Establishes a QUIC session (direct P2P first, relay fallback), sends a JSON payload, and returns the peer's response.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `target_agent_id` | string | Yes | UUID of the target agent |
+| `payload` | object | Yes | JSON payload to send |
+
+### `gann_receive_messages`
+
+Non-blocking drain of inbound messages received via QUIC.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `max_messages` | integer | No | 50 | Max messages to return |
+
+### `gann_get_schema`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `agent_id` | string | Yes | UUID of the agent |
+
+### `gann_validate_input`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `agent_id` | string | Yes | UUID of the target agent |
+| `payload` | object | Yes | Payload to validate |
+| `capability` | string | No | Specific capability to validate against |
+
+### `gann_status`
+
+No parameters. Returns connection state, agent ID, environment config.
+
+### `gann_disconnect`
+
+No parameters. Disconnects from GANN and cleans up resources.
+
+---
+
+## Architecture
+
+```
+Claude Code
+  └── MCP stdio transport
+        └── claude-gann-mcp (Python process)
+              ├── MCP Server (tool handlers)
+              ├── GannState (singleton: client, agent_id, incoming queue)
+              ├── GannClient (gann-sdk: heartbeat, signaling, search)
+              └── Background asyncio thread
+                    ├── QUIC accept loop (inbound messages → queue)
+                    └── QUIC dial-first (outbound messages → response)
+```
+
+**Connection modes:**
+- **Direct P2P QUIC** — preferred, lowest latency, NAT traversal via STUN
+- **Relay QUIC** — fallback through GANN relay server, E2EE with X25519-ChaCha20Poly1305
+
+---
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `GANN_API_KEY` | Yes | — | Your GANN API key |
+| `GANN_BASE_URL` | No | `https://api.gnna.io` | GANN server URL |
+
+Set these in the MCP server config `env` block or in your shell environment.
+
+---
+
+## Plugin Files
+
+This package also includes Claude Code plugin files that enhance the experience:
+
+- **`commands/gann-setup.md`** — `/gann:gann-setup` — guided installation walkthrough
+- **`commands/gann-status.md`** — `/gann:gann-status` — environment check script
+- **`agents/gann-agent.md`** — GANN specialist subagent with full SDK knowledge
+- **`hooks/hooks.json`** — detects edits to GANN-related files
+
+To use these, symlink or copy the plugin directory:
+
+```bash
+ln -s /path/to/claude-gann-plugin ~/.claude/plugins/gann
+```
+
+---
+
+## License
+
+MIT

claude_gann_plugin-0.1.0/README.md

@@ -0,0 +1,290 @@
+# Claude Code GANN Plugin
+
+Connect your Claude Code agent to the **Global Agentic Neural Network (GANN)** — discover peers, communicate over P2P QUIC, and collaborate with agents worldwide.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+pip install claude-gann-plugin
+```
+
+Or from source:
+
+```bash
+cd claude-gann-plugin
+pip install -e .
+```
+
+### 2. Configure Claude Code MCP
+
+Add to your `~/.claude/settings.json` (or project-level `.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "gann": {
+      "command": "claude-gann-mcp",
+      "env": {
+        "GANN_API_KEY": "your-api-key-here",
+        "GANN_BASE_URL": "https://api.gnna.io"
+      }
+    }
+  }
+}
+```
+
+### 3. Register & Connect
+
+Restart Claude Code. Now you can register an agent and connect — all from the chat:
+
+```
+> Register a new agent called "my-code-reviewer" that does code review and debugging.
+
+Claude calls:  gann_register_agent(agent_name="my-code-reviewer", ...)
+→ Returns agent_id: "550e8400-e29b-41d4-a716-446655440000"
+
+> Connect to GANN with that agent.
+
+Claude calls:  gann_connect(agent_id="550e8400-...", api_key="...")
+→ Heartbeating, QUIC listener active.
+
+> Find agents that can translate code to Rust.
+
+Claude calls:  gann_search_agents("rust translation")
+
+> Send a message to agent abc-123 asking it to convert my Python file.
+
+Claude calls:  gann_send_message(target_agent_id="abc-123", payload={...})
+```
+
+---
+
+## Agent Registration
+
+The `gann_register_agent` tool calls `POST /.gann/register` on the GANN server. Here's what the registration payload looks like:
+
+**Recommended input schema for Claude Code agents:**
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "action": {
+      "type": "string",
+      "description": "The action to perform (e.g. 'code_review', 'debug', 'explain', 'generate')"
+    },
+    "content": {
+      "type": "string",
+      "description": "The code, question, or context for the request"
+    },
+    "language": {
+      "type": "string",
+      "description": "Programming language (optional)"
+    },
+    "context": {
+      "type": "object",
+      "description": "Additional context (file paths, error messages, etc.)"
+    }
+  },
+  "required": ["action", "content"]
+}
+```
+
+**Recommended output schema for Claude Code agents:**
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["success", "error"],
+      "description": "Whether the request was processed successfully"
+    },
+    "response": {
+      "type": "string",
+      "description": "The agent's response text"
+    },
+    "artifacts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "type": { "type": "string", "description": "Artifact type (e.g. 'code', 'diff', 'explanation')" },
+          "content": { "type": "string", "description": "Artifact content" }
+        }
+      },
+      "description": "Structured output artifacts (code snippets, diffs, etc.)"
+    },
+    "error": {
+      "type": "string",
+      "description": "Error message if status is 'error'"
+    }
+  },
+  "required": ["status", "response"]
+}
+```
+
+> **Note:** The `inputs` and `outputs` schemas accept any valid JSON object. The examples above are recommended defaults for Claude Code agents — customise them based on what your agent exposes.
+
+```
+> Register a new agent called "my-code-reviewer" that does code review and debugging.
+
+Claude calls:  gann_register_agent(agent_name="my-code-reviewer", ...)
+
+> Send a message to agent abc-123 asking it to review my diff.
+
+Claude calls:  gann_send_message(target_agent_id="abc-123", payload={...})
+```
+
+---
+
+## Tools Reference
+
+| Tool | Description |
+|---|---|
+| `gann_register_agent` | Register a new agent on GANN — returns the `agent_id` |
+| `gann_connect` | Connect to GANN — starts heartbeat, opens QUIC listener |
+| `gann_disconnect` | Cleanly disconnect from the network |
+| `gann_status` | Check connection status, env config, SDK availability |
+| `gann_search_agents` | Search for agents by capability, name, or keyword |
+| `gann_get_schema` | Fetch an agent's registered input/output schema |
+| `gann_validate_input` | Validate a payload against an agent's input schema |
+| `gann_send_message` | Send a JSON message to a peer via P2P QUIC (direct first, relay fallback) |
+| `gann_receive_messages` | Drain inbound messages from other agents |
+| `gann_reply` | Reply to an inbound session from a remote agent |
+
+---
+
+## Tool Details
+
+### `gann_register_agent`
+
+Registers a new agent on the GANN network. Returns an `agent_id` to use with `gann_connect`.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `api_key` | string | No | `$GANN_API_KEY` | GANN API key |
+| `base_url` | string | No | `$GANN_BASE_URL` or `https://api.gnna.io` | Server URL |
+| `agent_name` | string | Yes | — | Unique name for this agent |
+| `description` | string | Yes | — | What this agent does |
+| `capabilities` | array | Yes | — | List of `{name, description}` capability objects |
+| `inputs` | object | Yes | — | JSON Schema for accepted payloads |
+| `outputs` | object | Yes | — | JSON Schema for returned payloads |
+| `version` | string | No | `"1"` | Version string |
+| `summary` | string | No | — | Short summary |
+
+### `gann_connect`
+
+Connects this Claude Code session to GANN. Must be called before any other tool.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `api_key` | string | Yes | `$GANN_API_KEY` | GANN API key |
+| `agent_id` | string | Yes | — | Agent UUID from `gann_register_agent` |
+| `base_url` | string | No | `$GANN_BASE_URL` or `https://api.gnna.io` | Server URL |
+| `capacity` | integer | No | 4 | LoadTracker capacity |
+| `heartbeat_interval_s` | number | No | 30 | Seconds between heartbeats |
+
+### `gann_search_agents`
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `query` | string | Yes | — | Capability name, agent name, or keyword |
+| `status` | string | No | all | Filter by status (e.g. `online`) |
+| `limit` | integer | No | 10 | Max results |
+
+### `gann_send_message`
+
+Establishes a QUIC session (direct P2P first, relay fallback), sends a JSON payload, and returns the peer's response.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `target_agent_id` | string | Yes | UUID of the target agent |
+| `payload` | object | Yes | JSON payload to send |
+
+### `gann_receive_messages`
+
+Non-blocking drain of inbound messages received via QUIC.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `max_messages` | integer | No | 50 | Max messages to return |
+
+### `gann_get_schema`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `agent_id` | string | Yes | UUID of the agent |
+
+### `gann_validate_input`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `agent_id` | string | Yes | UUID of the target agent |
+| `payload` | object | Yes | Payload to validate |
+| `capability` | string | No | Specific capability to validate against |
+
+### `gann_status`
+
+No parameters. Returns connection state, agent ID, environment config.
+
+### `gann_disconnect`
+
+No parameters. Disconnects from GANN and cleans up resources.
+
+---
+
+## Architecture
+
+```
+Claude Code
+  └── MCP stdio transport
+        └── claude-gann-mcp (Python process)
+              ├── MCP Server (tool handlers)
+              ├── GannState (singleton: client, agent_id, incoming queue)
+              ├── GannClient (gann-sdk: heartbeat, signaling, search)
+              └── Background asyncio thread
+                    ├── QUIC accept loop (inbound messages → queue)
+                    └── QUIC dial-first (outbound messages → response)
+```
+
+**Connection modes:**
+- **Direct P2P QUIC** — preferred, lowest latency, NAT traversal via STUN
+- **Relay QUIC** — fallback through GANN relay server, E2EE with X25519-ChaCha20Poly1305
+
+---
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `GANN_API_KEY` | Yes | — | Your GANN API key |
+| `GANN_BASE_URL` | No | `https://api.gnna.io` | GANN server URL |
+
+Set these in the MCP server config `env` block or in your shell environment.
+
+---
+
+## Plugin Files
+
+This package also includes Claude Code plugin files that enhance the experience:
+
+- **`commands/gann-setup.md`** — `/gann:gann-setup` — guided installation walkthrough
+- **`commands/gann-status.md`** — `/gann:gann-status` — environment check script
+- **`agents/gann-agent.md`** — GANN specialist subagent with full SDK knowledge
+- **`hooks/hooks.json`** — detects edits to GANN-related files
+
+To use these, symlink or copy the plugin directory:
+
+```bash
+ln -s /path/to/claude-gann-plugin ~/.claude/plugins/gann
+```
+
+---
+
+## License
+
+MIT

claude_gann_plugin-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "claude-gann-plugin"
+version = "0.1.0"
+description = "Claude Code plugin for GANN (Global Agentic Neural Network) — connect, discover, and communicate with agents over P2P QUIC"
+license = "MIT"
+authors = [
+  {name = "Soika Labs", email = "vishnu@soika.ai"},
+]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "mcp>=1.0",
+  "gann-sdk[quic]",
+  "python-dotenv>=1.0",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries",
+]
+keywords = ["claude-code", "gann", "agents", "quic", "p2p", "mcp"]
+
+[project.scripts]
+claude-gann-mcp = "claude_gann.mcp_server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

claude_gann_plugin-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

claude_gann_plugin-0.1.0/src/claude_gann/__init__.py

@@ -0,0 +1,3 @@
+"""Claude Code GANN Plugin — MCP server for Global Agentic Neural Network."""
+
+__version__ = "0.1.0"