name: aoconnect
description: CLI for interacting with AO processes using @permaweb/aoconnect - spawn processes, send messages, read results, monitor messages, and dry run
compatibility: Requires Node.js 18+, @permaweb/aoconnect package
metadata:
author: rakis
version: "0.0.1"

AOConnect Skill

A command-line interface for interacting with AO processes using the @permaweb/aoconnect library.

Phrase Mappings

Installation

Install the aoconnect skill and its dependency:

npx skills add https://github.com/permaweb/skills --skill aoconnect
npm install --save @permaweb/aoconnect

Or manually:

cd skills/aoconnect
npm install @permaweb/aoconnect

Prerequisites

• Node.js 18+
• @permaweb/aoconnect package installed
• Arweave wallet (JWK format) for signing messages

Available Functions

Spawn an AO Process

node skills/aoconnect/index.mjs spawn \
  --wallet ./wallet.json \
  --module <module-txid> \
  --scheduler <scheduler-address>

Options:
- --wallet <path> - Path to Arweave wallet JSON
- --module <txid> - The arweave TxID of the ao Module
- --scheduler <address> - The Arweave wallet address of a Scheduler Unit
- --data <string> - Optional data to include in spawn message

Example:

node skills/aoconnect/index.mjs spawn \
  --wallet ./wallet.json \
  --module "l3hbt-rIJ_dr9at-eQ3EVajHWMnxPNm9eBtXpzsFWZc" \
  --scheduler "_GQ33BkPtZrqxA84vM8Zk-N2aO0toNNu_C-l-rawrBA"

Output:

{
  "messageId": "l3hbt-rIJ_dr9at-eQ3EVajHWMnxPNm9eBtXpzsFWZc",
  "processId": "5SGJUlPwlenkyuG9-xWh0Rcf0azm8XEd5RBTiutgWAg",
  "height": 587540,
  "tags": [
    { "name": "App-Process", "value": "l3hbt..." },
    { "name": "App-Name", "value": "arweave-ao" }
  ]
}

Send a Message to an AO Process

node skills/aoconnect/index.mjs message \
  --wallet ./wallet.json \
  --process <process-id> \
  --data=<message-data> \
  --tags Name=Value,Another=Tag

Options:
- --wallet <path> - Path to Arweave wallet JSON (required)
- --process <id> - The ao Process ID (required)
- --data <string> - Message data (optional, random string if not provided)
- --tags <name=value,another=value> - Message tags (optional)

Example:

node skills/aoconnect/index.mjs message \
  --wallet ./wallet.json \
  --process "5SGJUlPwlenkyuG9-xWh0Rcf0azm8XEd5RBTiutgWAg" \
  --data="Hello from AO!" \
  --tags "Action=greet", "User=Rakis"

Output:

{
  "messageId": "l3hbt-rIJ_dr9at-eQ3EVajHWMnxPNm9eBtXpzsFWZc",
  "height": 587540,
  "tags": [
    { "name": "Action", "value": "greet" },
    { "name": "User", "value": "Rakis" },
    { "name": "Original-Message", "value": "l3hbt..." }
  ]
}

Read the Result of an AO Message Evaluation

node skills/aoconnect/index.mjs result \
  --message=<message-id> \
  --process=<process-id>

Options:
- --message=<id> - The ao message ID to evaluate (required)
- --process=<id> - The ao Process ID (required)

Example:

node skills/aoconnect/index.mjs result \
  --message="l3hbt-rIJ_dr9at-eQ3EVajHWMnxPNm9eBtXpzsFWZc" \
  --process="5SGJUlPwlenkyuG9-xWh0Rcf0azm8XEd5RBTiutgWAg"

Output:

{
  "messages": [
    {
      "messageId": "l3hbt-rIJ_dr9at-eQ3EVajHWMnxPNm9eBtXpzsFWZc",
      "tags": [
        { "name": "Action", "value": "greet" },
        { "name": "User", "value": "Rakis" }
      ],
      "data": "Hello from AO!"
    }
  ],
  "spawns": [],
  "output": {
    "messages": [
      {
        "from": "address",
        "to": "process-id",
        "target": "process-id",
        "tags": [
          { "name": "Response", "value": "Hello from AO!" }
        ],
        "data": "",
        "height": 587541
      }
    ],
    "size": 256
  },
  "error": null
}

Dry Run a Message (No Memory Commit)

node skills/aoconnect/index.mjs dryrun \
  --message=<message-id> \
  --process=<process-id>

Options:
- --message=<id> - The ao message ID to dry run (required)
- --process=<id> - The ao Process ID (required)

Example:

node skills/aoconnect/index.mjs dryrun \
  --message="l3hbt-rIJ_dr9at-eQ3EVajHWMnxPNm9eBtXpzsFWZc" \
  --process="5SGJUlPwlenkyuG9-xWh0Rcf0azm8XEd5RBTiutgWAg"

Output:

{
  "messages": [
    {
      "messageId": "l3hbt-rIJ_dr9at-eQ3EVajHWMnxPNm9eBtXpzsFWZc",
      "tags": [
        { "name": "Action", "value": "greet" }
      ]
    }
  ],
  "spawns": [],
  "output": {
    "messages": [
      {
        "from": "address",
        "to": "process-id",
        "target": "process-id",
        "tags": [
          { "name": "Response", "value": "Hello from AO!" }
        ],
        "height": 587541
      }
    ],
    "size": 256
  },
  "error": null
}

Note: Dry run evaluates the message but doesn't save it to memory. Perfect for testing without committing to the chain.

Monitor Messages

node skills/aoconnect/index.mjs monitor \
  --process <process-id> \
  --on-message "<callback>"

Options:
- --process <id> - The ao Process ID to monitor (required)
- --on-message "<function>" - JavaScript function to call for each new message (required)

Example:

node skills/aoconnect/index.mjs monitor \
  --process "5SGJUlPwlenkyuG9-xWh0Rcf0azm8XEd5RBTiutgWAg" \
  --on-message 'return { tags: msg.tags, data: msg.data }'

Note: In chat interface, use this pattern:

node skills/aoconnect/index.mjs monitor --process <id> --on-message "{console.log(msg.tags)}"

Connect to Custom Nodes

node skills/aoconnect/index.mjs connect --mu <url> --cu <url> --gateway <url>

Options:
- --mu <url> - Message Unit URL (optional)
- --cu <url> - Compute Unit URL (optional)
- --gateway <url> - Arweave gateway URL (optional)

Example:

node skills/aoconnect/index.mjs connect \
  --mu "https://mu.ao-testnet.xyz" \
  --cu "https://cu.ao-testnet.xyz" \
  --gateway "https://arweave.net"

Usage with AI Tools

Claude Code / OpenCode will automatically invoke the aoconnect skill when you:

use aoconnect to spawn <process>
use aoconnect to message <process> --data=<string>
use aoconnect to read result --message=<id>
use aoconnect to dryrun --message=<id>

The skill will prompt for wallet path if not configured.

Common Use Cases

Send a Transfer Message

node skills/aoconnect/index.mjs message \
  --wallet ./wallet.json \
  --process "ao-token-demo-AOe5Hdg4UQhOiE0ZYvRjB_8YDhROi3pA0YCEhPzb_KQ" \
  --data=<raw-balance-value> \
  --tags "Action=Transfer", "Recipient=<address>"

Dry Run Before Committing

Always dry run first to verify your message works:

node skills/aoconnect/index.mjs message \
  --wallet ./wallet.json \
  --process <process-id> \
  --data="test"

node skills/aoconnect/index.mjs dryrun \
  --message=<message-id> \
  --process=<process-id>

Monitor Active Process

node skills/aoconnect/index.mjs monitor \
  --process "<active-process-id>" \
  --on-message "{console.log('New message:', msg.tags)}"

Error Handling

Missing Wallet

Error: walletPath is required. Please provide a path to your Arweave wallet JSON file.

Solution: Provide a wallet path:

--wallet ./wallet.json

Invalid Process ID

Error: Failed to send message: Invalid process ID

Solution: Verify the process ID is correct and valid.

Authentication Failures

Error: Failed to send message: Unauthorized

Solution: Ensure your wallet has sufficient balance and proper permissions.

API Reference

messageAo(processId, options)

Send a message to an ao Process.

Parameters:
- processId (string): The ao Process ID
- options (Object): Message options
- data (string): Message data
- tags (Array): Message tags
- walletPath (string): Path to wallet JSON

Returns: Promise

resultAo(options)

Read the result of an ao message evaluation.

Parameters:
- options (Object)
- message (string): The message ID
- process (string): The Process ID

Returns: Promise

dryrunAo(options)

Dry run a message without committing to memory.

Parameters:
- options (Object)
- message (string): The message ID
- process (string): The Process ID

Returns: Promise

spawnAo(options)

Spawn an ao Process.

Parameters:
- options (Object)
- module (string): Module TxID
- scheduler (string): Scheduler address
- walletPath (string): Path to wallet JSON
- tags (Array): Tags for spawn message

Returns: Promise

monitorAo(options)

Monitor messages from a Process.

Parameters:
- options (Object)
- process (string): Process ID
- onMessage (Function): Callback for new messages

Returns: string - Monitor ID

unmonitorAo(monitorId)

Stop monitoring messages.

Parameters:
- monitorId (string): Monitor ID

connectAo(config)

Connect to ao nodes with custom configuration.

Parameters:
- config (Object)
- MU_URL (string): Message Unit URL
- CU_URL (string): Compute Unit URL
- GATEWAY_URL (string): Arweave gateway URL

Returns: Object - aoconnect functions

getConnection(config)

Get connected aoconnect functions.

Parameters:
- config (Object): Connection config

Returns: Object - aoconnect functions

Node.js vs Browser

This skill works in both Node.js and browser environments.

Node.js

import { messageAo, createDataItemSigner } from "./index.mjs";
import { readFileSync } from "node:fs";

const wallet = JSON.parse(readFileSync("./wallet.json", "utf-8"));
const result = await messageAo("process-id", {
  walletPath: "./wallet.json",
  data: "Hello AO!",
  tags: [{ name: "Action", value: "greet" }]
});

Browser

import { messageAo, createDataItemSigner } from "./index.mjs";

const result = await messageAo("process-id", {
  walletPath: "/path/to/wallet.json", // or loaded from localStorage
  data: "Hello AO!",
  tags: [{ name: "Action", value: "greet" }]
});

See Also

• AO Cookbook
• @permaweb/aoconnect Package
• AR.IO Documentation