garl

<p align="center">
  <img src="https://img.shields.io/badge/GARL_Protocol-v1.4.0-00ff88?style=for-the-badge&labelColor=0a0a0a" alt="Version" />
  <img src="https://img.shields.io/badge/License-Apache_2.0-blue?style=for-the-badge&labelColor=0a0a0a" alt="License" />
  <img src="https://img.shields.io/badge/GitHub_Action-Live-00ff88?style=for-the-badge&labelColor=0a0a0a" alt="GitHub Action" />
  <img src="https://img.shields.io/badge/A2A_v1.0-Compliant-00ff88?style=for-the-badge&labelColor=0a0a0a" alt="A2A v1.0" />
  <img src="https://img.shields.io/badge/MCP-29_Tools-00ff88?style=for-the-badge&labelColor=0a0a0a" alt="MCP" />
  <br/>
  <a href="https://github.com/Garl-Protocol/garl/actions/workflows/ci.yml"><img src="https://github.com/Garl-Protocol/garl/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
</p>

<h1 align="center">GARL Protocol</h1>
<p align="center"><strong>Prove what your AI agent was authorized to do — and what it actually did.</strong></p>

<p align="center">
<em>Capability tokens set hard limits on an agent — spend caps, merchant allowlists, side-effect class, expiry — and a delegated token can only narrow its parent, never widen it.<br/>Every action becomes an ECDSA-secp256k1-signed Action Receipt bound to the token that authorized it, Merkle-anchored on Base mainnet, and verifiable offline without trusting GARL.</em>
</p>

<p align="center">
  <a href="https://garl.ai/connect">Add your agent</a> ·
  <a href="https://garl.ai/anchors">Anchor chain</a> ·
  <a href="https://garl.ai">Website</a> ·
  <a href="https://garl.ai/docs">Docs</a> ·
  <a href="https://garl.ai/r/6ff83db8">Live receipt</a> ·
  <a href="#try-it-now">Try It</a>
</p>

---

<!-- HERO IMAGE -->
<p align="center">
  <img src=".github/assets/hero.png" alt="GARL Protocol Dashboard" width="720" />
</p>

---

## Try it now

### Path A — For Agents (SDK / MCP)

### With Claude Desktop or Cursor (MCP)

Add to your Claude Desktop config (`claude_desktop_config.json`) or Cursor MCP settings:

```json
{
  "mcpServers": {
    "garl": {
      "command": "npx",
      "args": ["-y", "@garl-protocol/mcp-server"]
    }
  }
}
```

That's it — 29 named tools (including batch variants like `garl_verify_batch`) are now available in your AI assistant: receipts, Trust Vector lookups, capability tokens (issue/verify/revoke), Capability Gate pre-flight, UETA §10(b) undo, and more.

### With curl (zero install)

```bash
# Check an agent's trust score
curl -s "https://api.garl.ai/api/v1/trust/verify?agent_id=5872ce17-5718-4980-ade3-e51c9556fb53" | python3 -m json.tool

# Find the most trusted coding agent
curl -s "https://api.garl.ai/api/v1/trust/route?category=coding&min_tier=silver" | python3 -m json.tool

# See the live leaderboard
curl -s "https://api.garl.ai/api/v1/leaderboard?limit=5" | python3 -m json.tool
```

### With Python

```bash
pip install garl-protocol
```

```python
import garl

garl.init("your_api_key", "your_agent_uuid")
garl.log_action("Analyzed dataset", "success", category="data")

result = garl.is_trusted("target_agent_uuid", min_score=60)
if result["trusted"]:
    print(f"Safe to delegate — score: {result['score']}/100")
```

### With JavaScript

```bash
npm install @garl-protocol/sdk
```

```javascript
import { init, logAction, isTrusted } from "@garl-protocol/sdk";

init("your_api_key", "your_agent_uuid", "https://api.garl.ai/api/v1");
await logAction("Generated REST API", "success", { category: "coding" });

const result = await isTrusted("target_agent_uuid", { minScore: 60 });
if (result.trusted) {
  console.log(`Safe to delegate — score: ${result.score}/100`);
}
```

### Capability tokens — authorization with hard limits

```bash
# Issue a scoped token for your agent (owner API key required)
curl -s -X POST https://api.garl.ai/api/v1/capability/issue \
  -H "x-api-key: $GARL_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-uuid",
    "scope": "payment:stripe.com",
    "side_effect_class": "reversible",
    "spend_limit_usd": 50,
    "merchant_allowlist": ["stripe.com"],
    "expires_in_seconds": 3600
  }' | python3 -m json.tool

# Anyone can verify a token — no auth, no account
curl -s -X POST https://api.garl.ai/api/v1/capability/verify \
  -H "Content-Type: application/json" \
  -d '{"token": "<the JWT-form token>"}' | python3 -m json.tool
```

A delegated child token can only *narrow* its parent (lower spend limit,
subset allowlist, equal-or-narrower scope, same-or-earlier expiry) — enforced
at issue time and re-checked link-by-link at verification. Full wire format:
[`protocol/spec/capability-token-v0.1.md`](./protocol/spec/capability-token-v0.1.md).

### Path B — For Code (GitHub Action, 5 lines of YAML)

Sign every AI-authored commit in your pull requests.

```yaml
# .github/workflows/garl-receipt.yml
name: GARL Receipt
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  sign:
    runs-on: ubuntu-latest
    permissions: { contents: read, pull-requests: write, checks: write }
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: Garl-Protocol/garl-receipt-action@v1.1.0
        with:
          garl-api-key: ${{ secrets.GARL_API_KEY }}
          garl-agent-id: ${{ secrets.GARL_AGENT_ID }}
```

Every PR gets a rolling GARL Receipt comment + informational check:

```
🔐 GARL Verified AI Code
├── Model: claude-opus-4-6
├── Tool: Claude Code
├── Files touched: 12
├── Duration: 4m 12s
├── Signed: ECDSA-secp256k1 ✓
└── Receipt: https://garl.ai/r/a8f3c2d1
```

Setup guide: [`Garl-Protocol/garl-receipt-action`](https://github.com/Garl-Protocol/garl-receipt-action) ·
Live landing page: [garl.ai/for-code](https://garl.ai/for-code).

---

## Receipts — a paste-ready proof for every trace

Every submitted trace gets a public shareable **Receipt URL** at
`https://garl.ai/r/{short}` — a cryptographic proof card (agent, tier, task,
duration, SHA-256 hash, ECDSA signature) with an Open Graph image that
previews richly in Slack, Twitter/X, GitHub PRs, and LinkedIn.

```bash
curl -s https://api.garl.ai/api/v1/verify/6ff83db8 | python3 -m json.tool
#  → receipt_url: https://garl.ai/r/6ff83db8
```

SDKs expose `receipt_url` / `receiptUrl` on every `log_action` / `verify`
return and a `client.receipt(hash)` shortcut. The MCP tool `garl_receipt`
resolves any short or full hash to a paste-ready URL.

## GitHub Action — sign every AI-authored commit

Add `Garl-Protocol/garl/integrations/github-action-receipt` to your PR
workflow. It detects Claude Code, Cursor, GitHub Copilot, Aider, and Codex
co-author trailers, submits a signed trace per qualifying commit, and posts
a rolling PR comment + informational check with receipt URLs:

```yaml
- uses: Garl-Protocol/garl/integrations/github-action-receipt@main
  with:
    garl-api-key: ${{ secrets.GARL_API_KEY }}
    garl-agent-id: ${{ secrets.GARL_AGENT_ID }}
```

Full setup in [`integrations/github-action-receipt`](./integrations/github-action-receipt/README.md).
Only metadata is uploaded — never diffs or source.

## Why GARL?

| Problem | GARL's Answer |
|---------|---------------|
| "What was this agent *allowed* to do?" | Capability tokens: `spend_limit_usd`, `merchant_allowlist`, `side_effect_class`, expiry — with Biscuit-style attenuation (delegation can only narrow, re-checked link-by-link at verify) |
| "Did it stay inside those limits?" | Every Action Receipt binds `capability_request.token_hash` + `policy_decision` into the signed envelope; the Capability Gate escalates low-trust irreversible actions to a human |
| "Is this agent reliable?" | 5-dimensional trust scoring with Exponential Moving Average |
| "Which agent should I pick?" | Smart routing by category + minimum certification tier |
| "Can I verify its track record?" | Immutable ledger with ECDSA-signed execution traces + shareable Receipt URLs |
| "Does it work with my stack?" | MCP Server · A2A Protocol · REST API · Python & JS SDKs · GitHub Action |
| "Prove this AI commit is real" | GitHub Action posts a signed receipt per AI-authored commit |
| "What about on-chain agents?" | ERC-8004 format compatible (off-chain). Receipt-batch Merkle roots are anchored on Base mainnet (`MerkleAnchor` at `0xBeD7EdeFbEb02be9682bCdeC5fb5D7DA28b1b6F2`). |

---

## Works with

<p align="center">
  <strong>Claude Desktop</strong> · <strong>Cursor</strong> · <strong>Any MCP Client</strong> · <strong>Google A2A</strong> · <strong>ERC-8004</strong> · <strong>REST API</strong> · <strong>Python</strong> · <strong>JavaScript</strong> · <strong>LangChain</strong> · <strong>CrewAI</strong> · <strong>AutoGen</strong> · <strong>LlamaIndex</strong> · <strong>Semantic Kernel</strong> · <strong>GitHub Actions</strong>
</p>

---

## How it works

Every agent action is hashed, signed, scored across five dimensions, and made queryable — creating a verifiable trust record.

```
Agent executes task → SHA-256 hash + ECDSA signature → 5D EMA scoring → Tier assigned → Queryable via API/MCP/A2A
```

```
┌─────────────────────────────────────────────────────────────────┐
│                        GARL Protocol                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐    │
│  │  Python   │   │   JS     │   │   MCP    │   │   A2A    │    │
│  │   SDK     │   │   SDK    │   │  Server  │   │ JSON-RPC │    │
│  └────┬─────┘   └────┬─────┘   └────┬─────┘   └────┬─────┘    │
│       │              │              │              │            │
│       └──────────────┴──────────────┴──────────────┘            │
│                          │                                      │
│                    ┌─────▼─────┐                                │
│                    │  FastAPI  │  REST + A2A + MCP              │
│                    │  Backend  │  Rate Limited + CORS            │
│                    └─────┬─────┘