Social Agent - ClarkOS

Overview

This example shows how to build a social agent that posts content based on mood and implements cooldown timers. It demonstrates mood-gated behavior and plugin patterns for social integrations.

View Source

See the complete example agent implementation on GitHub

What It Does

Posts content only when agent is expressive and healthy
Implements cooldown timers between posts
Logs activity for monitoring
Supports multiple platforms via configuration

Architecture

Tick ──► Mood Check ──► Expressive? ──► Cooldown Check ──► Post
                  │
                  └──► Other moods ──► Monitor only

The key insight: agents don’t always need to post. They wait for the right conditions. A plugin that manages posting with cooldowns: Key features:

Configurable cooldown period
Mood and health gating
Multi-platform support
Actions: post(content, platform), getStatus()

export function createSocialPlugin(config: {
  postCooldownMinutes: number;
  platforms: string[];
}): Plugin {
  let lastPostTime = 0;

  const canPost = () => Date.now() - lastPostTime > config.postCooldownMinutes * 60 * 1000;

  return {
    name: "social",
    version: "1.0.0",

    onTick(context) {
      // Only post when conditions are right
      if (context.state.mood === "expressive" && context.state.health > 50 && canPost()) {
        console.log("Ready to post");
      }
    },

    actions: {
      async post(params) { /* ... */ },
      async getStatus() { /* ... */ }
    }
  };
}

Reference: See the src/plugins directory in the example agent.

Logger Plugin

A simple companion plugin for monitoring:

export const loggerPlugin: Plugin = {
  name: "logger",
  version: "1.0.0",

  onTick(context) {
    console.log(`Mood: ${context.state.mood}, Health: ${context.state.health}`);
    console.log(`Memories: ${context.memories.length}`);
  }
};

Agent Setup

const agent = new Agent({
  backend: new ConvexBackend({ url: process.env.CONVEX_URL }),
  plugins: [
    loggerPlugin,
    createSocialPlugin({
      postCooldownMinutes: 60,  // 1 hour between posts
      platforms: ["twitter", "discord"],
    }),
  ],
});

Mood-Based Posting

The agent only posts when:

Mood is expressive — Agent has something to share
Health is above 50 — Agent has capacity
Cooldown has elapsed — Prevents spam

This creates natural, periodic engagement rather than constant output.

Rate Limits

Respect platform limits in your implementation:

Platform	Limit
Twitter	~300 tweets per 3 hours
Discord	5 messages per 5 seconds per channel

Build in cooldowns that exceed these limits to stay safe.

Running

npm run dev

# Check social plugin status
curl http://localhost:3001/actions/social/getStatus

# Manual post (for testing)
curl -X POST http://localhost:3001/actions/social/post \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"content": "Hello world", "platform": "twitter"}'

Best Practices

Quality over quantity — Let mood naturally gate output
Respect rate limits — Build in generous cooldowns
Log everything — Track all posts for debugging
Start conservative — Begin with longer cooldowns, reduce as needed

Next Steps

Basic Agent

Review the fundamentals.

Custom Plugins

Build your own integrations.

​Overview

View Source

​What It Does

​Architecture

​Social Plugin

​Logger Plugin

​Agent Setup

​Mood-Based Posting

​Rate Limits

​Running

​Best Practices

​Next Steps