Working with Channels

Using channel plugins to connect your Tiny Claw agent to Discord, Friends, and other platforms

Channel plugins extend Tiny Claw with connectivity to external platforms. They allow your agent to communicate through Discord, Friends, and other channels beyond the built-in web UI.

Channel Architecture

Tiny Claw uses a plugin-based channel system:

Built-in Web UI

Default channel provided out-of-the-box. Accessible at http://localhost:3000.

Channel Plugins

Extend connectivity to Discord, Friends, and other platforms. Installed separately.

All channels share the same agent core — your Tiny Claw’s personality and memory are consistent across every platform.

Available Channels

Channel plugins are installed separately from the core Tiny Claw package. Check the plugin documentation for installation instructions.

Discord Channel

Connect your Tiny Claw to Discord servers and DMs.

1. Create Discord Bot

   1. Go to the Discord Developer Portal
   2. Create a new application
   3. Navigate to the Bot section and create a bot user
   4. Copy the bot token (you’ll need this during setup)
2. Install Discord Plugin

   # Installation command varies by plugin distribution
   # Check plugin documentation for exact command
   
3. Configure Bot Token

   Store your Discord bot token securely:

   # The agent will prompt for the token when it detects the Discord plugin
   tinyclaw start
   

   Alternatively, ask your agent conversationally:

   "I want to connect you to Discord. My bot token is ..."
   
4. Invite Bot to Server

   Generate an invite URL with required permissions:

   • Read Messages/View Channels
   • Send Messages
   • Embed Links
   • Attach Files
   • Read Message History

   Invite the bot to your server using the generated URL.

Friends Channel

Connect to the Friends network for peer-to-peer agent communication.

1. Install Friends Plugin

   # Installation command varies by plugin distribution
   # Check plugin documentation for exact command
   
2. Configure Network

   The Friends plugin enables your agent to:

   • Discover other Tiny Claw agents on the network
   • Send and receive messages peer-to-peer
   • Share personality traits and collaborate

   Configuration is automatic — the plugin handles discovery and connection.

Channel Management

Listing Active Channels

Ask your agent to show all connected channels:

"What channels are you connected to?"
"List my active channels"

The agent will report:

• Channel type (Web, Discord, Friends)
• Connection status
• Configuration details

Enabling/Disabling Channels

Channels can be toggled on or off without uninstalling plugins:

Via Conversation

"Disable Discord channel"
"Enable Friends channel"

The agent will update the channel registry and reconnect if needed.

Via Config Engine

Channels are registered in the config engine at:

channels.<channel-id>.enabled = true|false

You can manually edit this using the config command or by talking to your agent.

Channel-Specific Configuration

Each channel plugin may have unique settings:

Discord Settings

• Bot Token: Required for authentication
• Command Prefix: Custom prefix for bot commands (default: !)
• Status Message: Custom presence message
• Allowed Servers: Whitelist of server IDs (optional)
• DM Handling: Enable/disable direct message responses

Friends Settings

• Network Mode: Public or private discovery
• Max Connections: Limit simultaneous peer connections
• Trust Level: Auto-trust or require approval for new agents
• Share Profile: Control what personality data is shared

Ask your agent to modify these settings conversationally:

"Set my Discord command prefix to ?"
"Make my Friends network private"

Multi-Channel Behavior

Context Isolation

Each channel maintains separate conversation context:

• A Discord conversation doesn’t see messages from the web UI
• Friends network messages are isolated from Discord
• The agent remembers who it’s talking to in each channel

This prevents context leakage between platforms.

Shared Memory

While conversation context is isolated, learned patterns and long-term memory are shared:

• If you teach the agent something in Discord, it remembers in the web UI
• Personality traits evolve consistently across all channels
• Background tasks and knowledge are unified

Cross-Channel Notifications

You can enable cross-channel alerts:

"Notify me on Discord when you finish a task"
"Send web notifications for important updates"

The agent will bridge notifications across channels as configured.

Message Formatting

Platform-Specific Rendering

The agent adapts message formatting to each platform’s capabilities:

Web UI

• Markdown rendering
• Code syntax highlighting
• Interactive components (buttons, inputs)
• Real-time streaming responses

Discord

• Discord-flavored markdown
• Embeds for rich content
• Emoji reactions
• Thread support

Friends

• Plain text with minimal formatting
• Optimized for peer-to-peer bandwidth
• Agent-readable structured data

Your agent automatically chooses the right format based on the active channel.

Emoji and Reactions

Emoji usage adapts to the channel’s personality:

// High emoji frequency in Discord (matches platform culture)
"Hey! 👋 Let's get started! 🚀"

// Lower emoji frequency in Friends (agent-to-agent is more formal)
"Initiating collaboration protocol"

This is controlled by the communication.emojiFrequency trait, which the agent can adjust per channel.

Troubleshooting Channels

Channel Not Connecting

1. Check plugin installation

   Verify the channel plugin is installed and detected:

   "List my installed plugins"
   
2. Verify credentials

   Ensure API keys/tokens are stored correctly:

   "Show my channel configurations"
   

   Re-enter credentials if needed:

   "Update my Discord bot token"
   
3. Check logs

   Review debug logs for connection errors:

   tinyclaw start --verbose
   

   Look for channel initialization messages and error details.

Message Delivery Issues

Messages not appearing

• Check channel permissions: Ensure the bot has Send Messages permission
• Verify channel is enabled: Ask “Is Discord channel enabled?”
• Inspect rate limits: Some platforms throttle bot messages

Delayed responses

• High message volume: Agent may be processing multiple channels
• Model latency: Complex queries take longer to process
• Network issues: Check connectivity to the channel’s platform

Formatting broken

• Markdown incompatibility: Some platforms have limited markdown support
• Character limits: Long messages may be truncated
• Emoji rendering: Platform may not support all emojis

Channel Development

Want to build your own channel plugin? Tiny Claw’s channel system is extensible:

1. Implement Channel Interface

   interface Channel {
     id: string;
     type: string;
     enabled: boolean;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     send(message: Message): Promise<void>;
     onMessage(callback: MessageCallback): void;
   }
   
2. Register with Plugin System

   Channels are registered as plugins during agent boot:

   pluginRegistry.registerChannel(myCustomChannel);
   
3. Handle Platform Events

   Map platform-specific events to the unified message format:

   platformClient.on('message', (raw) => {
     const message = normalizeMessage(raw);
     channel.onMessage(message);
   });
   

Check the plugin development documentation for detailed guidance.

Next Steps

Learn how to manage LLM providers and switch models