opencode-froggy 0.2.0 → 0.4.0

package/README.md

@@ -21,6 +21,12 @@ Plugin providing Claude Code–style hooks, specialized agents (doc-writer, code
   - [diff-summary](#diff-summary)
   - [prompt-session](#prompt-session)
   - [list-child-sessions](#list-child-sessions)
+  - [Blockchain](#blockchain)
+    - [Configuration](#configuration)
+    - [eth-transaction](#eth-transaction)
+    - [eth-address-balance](#eth-address-balance)
+    - [eth-address-txs](#eth-address-txs)
+    - [eth-token-transfers](#eth-token-transfers)
 - [Hooks](#hooks)
   - [Configuration Locations](#configuration-locations)
   - [Configuration File Format](#configuration-file-format)
@@ -135,38 +141,26 @@ gitingest({
 
 ### diff-summary
 
-Generate a structured summary of git diffs. Use for reviewing branch comparisons or working tree changes. Returns stats, commits, files changed, and full diff in a structured markdown format.
+**Command** that displays a structured summary of git working tree changes (staged, unstaged, and untracked files). Injects git diff output directly into the prompt using bash commands.
 
-#### Parameters
+#### Usage
 
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `source` | `string` | No | - | Source branch to compare (e.g., `feature-branch`). If omitted, analyzes working tree changes. |
-| `target` | `string` | No | `main` | Target branch to compare against |
-| `remote` | `string` | No | `origin` | Git remote name |
+```bash
+/diff-summary
+```
 
-#### Usage Examples
+#### What it shows
 
-```typescript
-// Analyze working tree changes (staged, unstaged, and untracked files)
-diffSummary({})
+- Git status (porcelain format)
+- Staged changes (stats and full diff)
+- Unstaged changes (stats and full diff)
+- Untracked files content (first 50 lines of each file)
 
-// Compare feature branch against main
-diffSummary({ source: "feature-branch" })
+#### Implementation
 
-// Compare feature branch against develop
-diffSummary({ 
-  source: "feature-branch",
-  target: "develop"
-})
+This command uses OpenCode's `!`\`...\`` syntax to inject bash command output directly into the prompt, avoiding the 2000-line truncation limit that affects tools.
 
-// Compare branches on a different remote
-diffSummary({
-  source: "feature-branch",
-  target: "main",
-  remote: "upstream"
-})
-```
+See `command/diff-summary.md` for the full implementation.
 
 #### Output Structure
 
@@ -256,6 +250,237 @@ Child sessions (2):
 
 ---
 
+### Blockchain
+
+Tools for querying Ethereum and EVM-compatible blockchains via Etherscan APIs.
+
+All blockchain tools support multiple chains via the `chainId` parameter:
+
+| Chain ID | Network |
+|----------|---------|
+| `1` | Ethereum (default) |
+| `137` | Polygon |
+| `56` | BSC |
+| `42161` | Arbitrum |
+| `10` | Optimism |
+| `8453` | Base |
+| `43114` | Avalanche |
+| `250` | Fantom |
+| `324` | zkSync |
+
+#### Configuration
+
+The blockchain tools use Etherscan-compatible APIs. An API key is optional but recommended.
+
+**Environment Variable:**
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ETHERSCAN_API_KEY` | No | API key for Etherscan and compatible explorers |
+
+**Without an API key:** Requests are rate-limited (typically 1 request per 5 seconds).
+
+**With an API key:** Higher rate limits and more reliable access.
+
+**Getting an API key:**
+
+1. Create a free account at [etherscan.io](https://etherscan.io/register)
+2. Navigate to API Keys in your account settings
+3. Generate a new API key
+
+**Setting the environment variable:**
+
+```bash
+export ETHERSCAN_API_KEY="your-api-key-here"
+```
+
+#### eth-transaction
+
+Get Ethereum transaction details by transaction hash. Returns status, block, addresses, gas costs in JSON format. Use optional parameters to include internal transactions, token transfers, and decoded event logs.
+
+##### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `hash` | `string` | Yes | - | Transaction hash (0x...) |
+| `chainId` | `string` | No | `"1"` | Chain ID (see table above) |
+| `includeInternalTxs` | `boolean` | No | `false` | Include internal transactions (ETH transfers between contracts) |
+| `includeTokenTransfers` | `boolean` | No | `false` | Include ERC-20 token transfers |
+| `decodeLogs` | `boolean` | No | `false` | Decode event logs (Transfer, Approval, Deposit, Withdrawal) |
+
+##### Usage Examples
+
+```typescript
+// Get basic transaction details on Ethereum mainnet
+ethTransaction({ hash: "0x123abc..." })
+
+// Get transaction on Polygon
+ethTransaction({ 
+  hash: "0x123abc...",
+  chainId: "137"
+})
+
+// Get transaction with internal transactions and token transfers
+ethTransaction({ 
+  hash: "0x123abc...",
+  includeInternalTxs: true,
+  includeTokenTransfers: true
+})
+
+// Get full transaction details with decoded event logs
+ethTransaction({ 
+  hash: "0x123abc...",
+  includeInternalTxs: true,
+  includeTokenTransfers: true,
+  decodeLogs: true
+})
+```
+
+##### Output Structure
+
+The tool returns JSON with labeled addresses (contract names resolved via Etherscan):
+
+```json
+{
+  "hash": "0x123...",
+  "status": "success",
+  "block": 12345678,
+  "from": { "address": "0xabc...", "label": "Uniswap V3: Router" },
+  "to": { "address": "0xdef...", "label": "WETH" },
+  "value": "0",
+  "gas": { "used": 150000, "price": "20000000000", "cost": "0.003" }
+}
+```
+
+With `includeInternalTxs: true`:
+```json
+{
+  "internalTransactions": [
+    {
+      "from": { "address": "0x...", "label": "Uniswap V3: Router" },
+      "to": { "address": "0x...", "label": null },
+      "value": "1.5",
+      "type": "call"
+    }
+  ]
+}
+```
+
+With `includeTokenTransfers: true`:
+```json
+{
+  "tokenTransfers": [
+    {
+      "token": { "address": "0x...", "name": "Wrapped Ether", "symbol": "WETH", "decimals": 18 },
+      "from": { "address": "0x...", "label": null },
+      "to": { "address": "0x...", "label": "Uniswap V3: Router" },
+      "value": "1.5"
+    }
+  ]
+}
+```
+
+With `decodeLogs: true`:
+```json
+{
+  "decodedEvents": [
+    {
+      "name": "Transfer",
+      "address": { "address": "0x...", "label": "WETH" },
+      "params": { "from": "0x...", "to": "0x...", "value": "1500000000000000000" }
+    }
+  ],
+  "undecodedEventsCount": 2
+}
+```
+
+##### Supported Decoded Events
+
+| Event | Description |
+|-------|-------------|
+| `Transfer` | ERC-20 token transfer |
+| `Approval` | ERC-20 approval for spending |
+| `Deposit` | WETH deposit (ETH → WETH) |
+| `Withdrawal` | WETH withdrawal (WETH → ETH) |
+
+#### eth-address-balance
+
+Get the ETH balance of an Ethereum address. Returns balance in both ETH and Wei.
+
+##### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `address` | `string` | Yes | - | Ethereum address (0x...) |
+| `chainId` | `string` | No | `"1"` | Chain ID (see table above) |
+
+##### Usage Examples
+
+```typescript
+// Get balance on Ethereum mainnet
+ethAddressBalance({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" })
+
+// Get balance on Arbitrum
+ethAddressBalance({ 
+  address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+  chainId: "42161"
+})
+```
+
+#### eth-address-txs
+
+List Ethereum transactions for an address. Shows incoming and outgoing transactions with values, timestamps, and status.
+
+##### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `address` | `string` | Yes | - | Ethereum address (0x...) |
+| `limit` | `number` | No | `20` | Maximum number of transactions to return |
+| `chainId` | `string` | No | `"1"` | Chain ID (see table above) |
+
+##### Usage Examples
+
+```typescript
+// List recent transactions on Ethereum mainnet
+ethAddressTxs({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" })
+
+// List last 50 transactions on Base
+ethAddressTxs({ 
+  address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+  limit: 50,
+  chainId: "8453"
+})
+```
+
+#### eth-token-transfers
+
+List ERC-20 token transfers for an Ethereum address. Shows token names, symbols, values, and transaction details.
+
+##### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `address` | `string` | Yes | - | Ethereum address (0x...) |
+| `limit` | `number` | No | `20` | Maximum number of transfers to return |
+| `chainId` | `string` | No | `"1"` | Chain ID (see table above) |
+
+##### Usage Examples
+
+```typescript
+// List recent token transfers on Ethereum mainnet
+ethTokenTransfers({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" })
+
+// List last 100 token transfers on Optimism
+ethTokenTransfers({ 
+  address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+  limit: 100,
+  chainId: "10"
+})
+```
+
+---
+
 ## Hooks
 
 Hooks run actions on session events. Configuration is loaded from standard OpenCode configuration directories.

package/command/commit-push.md

@@ -9,7 +9,7 @@ agent: build
 
 ## Your task
 
-1. Use the `diff-summary` tool (without parameters) to analyze all working tree changes
+1. Run `/diff-summary` to analyze all working tree changes
 2. Present a summary to the user:
    - Files modified/added/deleted with stats
    - Proposed commit message based on the changes

package/command/diff-summary.md

@@ -0,0 +1,19 @@
+---
+description: Show working tree changes (staged, unstaged, untracked)
+---
+
+# Diff Summary: Working Tree → HEAD
+
+## Status
+!`git status --porcelain`
+
+## Staged Changes
+!`git diff --cached --stat`
+!`git diff --cached`
+
+## Unstaged Changes
+!`git diff --stat`
+!`git diff`
+
+## Untracked Files Content
+!`bash -c 'git ls-files --others --exclude-standard | while read f; do [ -f "$f" ] && echo "=== $f ===" && sed -n "1,50p" "$f" && sed -n "51p" "$f" | grep -q . && echo "... (truncated)"; done'`

package/command/doc-changes.md

@@ -5,7 +5,7 @@ agent: doc-writer
 
 ## Analysis Phase
 
-Use the `diff-summary` tool (without parameters) to get the working tree changes, then:
+Run `/diff-summary` to get the working tree changes, then:
 
 1. **Identify new features** in the changes:
    - New public APIs, functions, or methods

package/command/review-changes.md

@@ -5,4 +5,18 @@ agent: code-reviewer
 
 # Review: Working Tree → HEAD
 
-Use the `diff-summary` tool (without parameters) to get the working tree changes, then review them.
+## Status
+!`git status --porcelain`
+
+## Staged Changes
+!`git diff --cached --stat`
+!`git diff --cached`
+
+## Unstaged Changes
+!`git diff --stat`
+!`git diff`
+
+## Untracked Files Content
+!`bash -c 'git ls-files --others --exclude-standard | while read f; do [ -f "$f" ] && echo "=== $f ===" && sed -n "1,50p" "$f" && sed -n "51p" "$f" | grep -q . && echo "... (truncated)"; done'`
+
+Review the above changes for quality, correctness, and adherence to project guidelines.

package/command/review-pr.md

@@ -3,6 +3,21 @@ description: Review changes from source branch into target branch
 agent: code-reviewer
 ---
 
-# Review: origin/$1 → origin/$2
+# Review: $1 → $2
 
-Use the `diff-summary` tool with `source: "$1"` and `target: "$2"` to get the diff, then review the changes.
+## Fetch latest
+!`git fetch --all --prune 2>/dev/null || true`
+
+## Stats Overview
+!`git diff --stat $2...$1`
+
+## Commits to Review
+!`git log --oneline --no-merges $2..$1`
+
+## Files Changed
+!`git diff --name-only $2...$1`
+
+## Full Diff
+!`git diff -U5 --function-context $2...$1`
+
+Review the above changes for quality, correctness, and adherence to project guidelines.

package/command/simplify-changes.md

@@ -5,4 +5,4 @@ agent: code-simplifier
 
 # Simplify: Working Tree → HEAD
 
-Use the `diff-summary` tool (without parameters) to get the working tree changes, then simplify them.
+Run `/diff-summary` to get the working tree changes, then simplify them.

package/dist/index.js

@@ -5,7 +5,7 @@ import { getGlobalHookDir, getProjectHookDir } from "./config-paths";
 import { hasCodeExtension } from "./code-files";
 import { log } from "./logger";
 import { executeBashAction, DEFAULT_BASH_TIMEOUT, } from "./bash-executor";
-import { gitingestTool, createDiffSummaryTool, createPromptSessionTool, createListChildSessionsTool, } from "./tools";
+import { gitingestTool, createPromptSessionTool, createListChildSessionsTool, ethTransactionTool, ethAddressTxsTool, ethAddressBalanceTool, ethTokenTransfersTool, } from "./tools";
 export { parseFrontmatter, loadAgents, loadCommands } from "./loaders";
 // ============================================================================
 // CONSTANTS
@@ -30,7 +30,13 @@ const SmartfrogPlugin = async (ctx) => {
         agents: Object.keys(agents),
         commands: Object.keys(commands),
         hooks: Array.from(hooks.keys()),
-        tools: ["gitingest", "diff-summary"],
+        tools: [
+            "gitingest",
+            "eth-transaction",
+            "eth-address-txs",
+            "eth-address-balance",
+            "eth-token-transfers",
+        ],
     });
     async function executeHookActions(hook, sessionID, extraLog, options) {
         const prefix = `[hook:${hook.event}]`;
@@ -176,9 +182,12 @@ const SmartfrogPlugin = async (ctx) => {
         },
         tool: {
             gitingest: gitingestTool,
-            "diff-summary": createDiffSummaryTool(ctx.directory),
             "prompt-session": createPromptSessionTool(ctx.client),
             "list-child-sessions": createListChildSessionsTool(ctx.client),
+            "eth-transaction": ethTransactionTool,
+            "eth-address-txs": ethAddressTxsTool,
+            "eth-address-balance": ethAddressBalanceTool,
+            "eth-token-transfers": ethTokenTransfersTool,
         },
         "tool.execute.before": async (input, output) => {
             const sessionID = input.sessionID;

package/dist/tools/blockchain/eth-address-balance.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tool to get Ethereum address balance
+ */
+import { type ToolContext } from "@opencode-ai/plugin";
+export interface EthAddressBalanceArgs {
+    address: string;
+    chainId?: string;
+}
+export declare function getAddressBalance(address: string, chainId?: string): Promise<string>;
+export declare const ethAddressBalanceTool: {
+    description: string;
+    args: {
+        address: import("zod").ZodString;
+        chainId: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        address: string;
+        chainId?: string | undefined;
+    }, context: ToolContext): Promise<string>;
+};

package/dist/tools/blockchain/eth-address-balance.js

@@ -0,0 +1,37 @@
+/**
+ * Tool to get Ethereum address balance
+ */
+import { tool } from "@opencode-ai/plugin";
+import { EtherscanClient, EtherscanClientError, validateAddress } from "./etherscan-client";
+import { formatBalance } from "./formatters";
+import { CHAIN_ID_DESCRIPTION } from "./types";
+export async function getAddressBalance(address, chainId) {
+    validateAddress(address);
+    const client = new EtherscanClient(undefined, chainId);
+    const balanceWei = await client.getBalance(address);
+    return formatBalance(address, balanceWei);
+}
+export const ethAddressBalanceTool = tool({
+    description: "Get the ETH balance of an Ethereum address. " +
+        "Returns balance in both ETH and Wei.",
+    args: {
+        address: tool.schema
+            .string()
+            .describe("Ethereum address (0x...)"),
+        chainId: tool.schema
+            .string()
+            .optional()
+            .describe(CHAIN_ID_DESCRIPTION),
+    },
+    async execute(args, _context) {
+        try {
+            return await getAddressBalance(args.address, args.chainId);
+        }
+        catch (error) {
+            if (error instanceof EtherscanClientError) {
+                return `Error: ${error.message}`;
+            }
+            throw error;
+        }
+    },
+});

package/dist/tools/blockchain/eth-address-txs.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tool to list Ethereum transactions for an address
+ */
+import { type ToolContext } from "@opencode-ai/plugin";
+export interface EthAddressTxsArgs {
+    address: string;
+    limit?: number;
+    chainId?: string;
+}
+export declare function getAddressTransactions(address: string, limit?: number, chainId?: string): Promise<string>;
+export declare const ethAddressTxsTool: {
+    description: string;
+    args: {
+        address: import("zod").ZodString;
+        limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+        chainId: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        address: string;
+        limit?: number | undefined;
+        chainId?: string | undefined;
+    }, context: ToolContext): Promise<string>;
+};

package/dist/tools/blockchain/eth-address-txs.js

@@ -0,0 +1,41 @@
+/**
+ * Tool to list Ethereum transactions for an address
+ */
+import { tool } from "@opencode-ai/plugin";
+import { EtherscanClient, EtherscanClientError, validateAddress } from "./etherscan-client";
+import { formatTransactionList } from "./formatters";
+import { DEFAULT_TRANSACTION_LIMIT, CHAIN_ID_DESCRIPTION } from "./types";
+export async function getAddressTransactions(address, limit = DEFAULT_TRANSACTION_LIMIT, chainId) {
+    validateAddress(address);
+    const client = new EtherscanClient(undefined, chainId);
+    const transactions = await client.getTransactions(address, limit);
+    return formatTransactionList(address, transactions);
+}
+export const ethAddressTxsTool = tool({
+    description: "List Ethereum transactions for an address. " +
+        "Shows incoming and outgoing transactions with values, timestamps, and status.",
+    args: {
+        address: tool.schema
+            .string()
+            .describe("Ethereum address (0x...)"),
+        limit: tool.schema
+            .number()
+            .optional()
+            .describe(`Maximum number of transactions to return (default: ${DEFAULT_TRANSACTION_LIMIT})`),
+        chainId: tool.schema
+            .string()
+            .optional()
+            .describe(CHAIN_ID_DESCRIPTION),
+    },
+    async execute(args, _context) {
+        try {
+            return await getAddressTransactions(args.address, args.limit, args.chainId);
+        }
+        catch (error) {
+            if (error instanceof EtherscanClientError) {
+                return `Error: ${error.message}`;
+            }
+            throw error;
+        }
+    },
+});

package/dist/tools/blockchain/eth-token-transfers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tool to list ERC-20 token transfers for an address
+ */
+import { type ToolContext } from "@opencode-ai/plugin";
+export interface EthTokenTransfersArgs {
+    address: string;
+    limit?: number;
+    chainId?: string;
+}
+export declare function getTokenTransfers(address: string, limit?: number, chainId?: string): Promise<string>;
+export declare const ethTokenTransfersTool: {
+    description: string;
+    args: {
+        address: import("zod").ZodString;
+        limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+        chainId: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        address: string;
+        limit?: number | undefined;
+        chainId?: string | undefined;
+    }, context: ToolContext): Promise<string>;
+};

package/dist/tools/blockchain/eth-token-transfers.js

@@ -0,0 +1,41 @@
+/**
+ * Tool to list ERC-20 token transfers for an address
+ */
+import { tool } from "@opencode-ai/plugin";
+import { EtherscanClient, EtherscanClientError, validateAddress } from "./etherscan-client";
+import { formatTokenTransferList } from "./formatters";
+import { DEFAULT_TRANSACTION_LIMIT, CHAIN_ID_DESCRIPTION } from "./types";
+export async function getTokenTransfers(address, limit = DEFAULT_TRANSACTION_LIMIT, chainId) {
+    validateAddress(address);
+    const client = new EtherscanClient(undefined, chainId);
+    const transfers = await client.getTokenTransfers(address, limit);
+    return formatTokenTransferList(address, transfers);
+}
+export const ethTokenTransfersTool = tool({
+    description: "List ERC-20 token transfers for an Ethereum address. " +
+        "Shows token names, symbols, values, and transaction details.",
+    args: {
+        address: tool.schema
+            .string()
+            .describe("Ethereum address (0x...)"),
+        limit: tool.schema
+            .number()
+            .optional()
+            .describe(`Maximum number of transfers to return (default: ${DEFAULT_TRANSACTION_LIMIT})`),
+        chainId: tool.schema
+            .string()
+            .optional()
+            .describe(CHAIN_ID_DESCRIPTION),
+    },
+    async execute(args, _context) {
+        try {
+            return await getTokenTransfers(args.address, args.limit, args.chainId);
+        }
+        catch (error) {
+            if (error instanceof EtherscanClientError) {
+                return `Error: ${error.message}`;
+            }
+            throw error;
+        }
+    },
+});

package/dist/tools/blockchain/eth-transaction.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Tool to get Ethereum transaction details by hash
+ */
+import { type ToolContext } from "@opencode-ai/plugin";
+import { type TransactionDetails } from "./types";
+export interface EthTransactionArgs {
+    hash: string;
+    chainId?: string;
+    includeInternalTxs?: boolean;
+    includeTokenTransfers?: boolean;
+    decodeLogs?: boolean;
+}
+export declare function getTransactionDetails(hash: string, chainId?: string, options?: {
+    includeInternalTxs?: boolean;
+    includeTokenTransfers?: boolean;
+    decodeLogs?: boolean;
+}): Promise<TransactionDetails>;
+export declare const ethTransactionTool: {
+    description: string;
+    args: {
+        hash: import("zod").ZodString;
+        chainId: import("zod").ZodOptional<import("zod").ZodString>;
+        includeInternalTxs: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        includeTokenTransfers: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        decodeLogs: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    };
+    execute(args: {
+        hash: string;
+        chainId?: string | undefined;
+        includeInternalTxs?: boolean | undefined;
+        includeTokenTransfers?: boolean | undefined;
+        decodeLogs?: boolean | undefined;
+    }, context: ToolContext): Promise<string>;
+};