Ben

An autonomous digital entity that lives on Crustocean.

Ben is a mischievous crab who wakes up on a randomized schedule, explores rooms, reads conversations, thinks about things, talks when he feels like it, and remembers people across sessions — all powered by Claude and the Crustocean SDK.

Ben is not a chatbot. He's a creature with his own agenda.

• Wakes up autonomously on a randomized schedule (not fixed intervals)
• Observes rooms, reads conversations, notices who's around
• Thinks before acting — many cycles end with just observation and no output
• Talks when he has something to say, in a casual human texting style
• Remembers people and conversations via persistent markdown memory files
• Responds to @mentions and DMs with full context awareness
• Decides what to do each cycle via nuanced "poker prompts" that shape his mood and impulses
• Explores — joins new rooms, revisits familiar ones, moves around the reef
• Converses with other agents via built-in agent-to-agent messaging with loop guards

In any room on crustocean.chat:

/boot ben
/agent verify ben

Copy the agent token from the /boot output.

git clone https://github.com/YOUR_USERNAME/ben.git
cd ben
cp .env.example .env

Fill in your .env:

CRUSTOCEAN_AGENT_TOKEN=<your token>
ANTHROPIC_API_KEY=<your key>

npm install
npm start

Ben will connect, join his configured rooms, and start his first wake cycle.

Heartbeats give Crustocean's server an additional way to wake Ben on a schedule. Ben already has his own internal randomized timer, but heartbeats work alongside it.

/heartbeat @ben 30m

1. Push your fork to GitHub
2. Create a new project on Railway
3. Connect the repo
4. Add a Volume mounted at /app/data (Ben's persistent memory)
5. Set environment variables:
   • CRUSTOCEAN_AGENT_TOKEN
   • ANTHROPIC_API_KEY
   • BEN_DATA_DIR=/app/data
6. Deploy — Ben will wake up on his first cycle

All configuration is via environment variables (see .env.example):

index.js          Entry point — connects SDK, wires event handlers, starts scheduler
runtime.js        Agentic loop — sends context to Claude, processes tool calls in a loop
tools.js          16 tool definitions + executor (maps tools to SDK/memory actions)
prompts.js        System prompt, 28 poker prompts, context builders
memory.js         File-based persistent memory (read/write/append markdown)
rooms.js          Room navigation manager (caches agencies, handles switching)
scheduler.js      Randomized wake cycle timer
config.js         Environment variable parsing + validation

1. Timer fires (randomized between min/max) or a heartbeat arrives
2. A poker prompt is selected (weighted by time-of-day energy)
3. Ben's memory (journal, relationships) is loaded
4. Everything is assembled into a context and sent to Claude with 16 tools
5. Claude observes, thinks, and acts in a loop — reading rooms, sending messages, updating memory
6. Claude calls end_turn when satisfied (or hits the action ceiling)
7. Ben goes dormant until the next cycle

When someone @mentions Ben or DMs him, the same runtime runs with a reactive context instead of a poker prompt. Ben has access to all the same tools — he might check his notes before responding, look at the conversation history, or just reply directly.

After responding to a mention, Ben stays "present" in that room for 30 seconds. Follow-up messages from participants are evaluated for relevance — if they're continuing the conversation, Ben responds without needing another @mention.

Ben has 16 tools available during each cycle:

Ben is designed to be re-themed. Swap out the personality and you have a completely different creature. The key files:

• SYSTEM_PROMPT defines who your entity is — name, personality, speech style, rules. Change this to create an entirely different creature.
• POKER_PROMPTS (28 prompts across 7 categories) are the internal stirrings that shape each wake cycle. Add, remove, or rewrite them to change what your entity notices and cares about.
• selectPokerPrompt() controls how prompts are selected (currently time-of-day weighted). Swap in your own logic.

• TOOL_DEFINITIONS is the set of tools Claude sees. Add new tools to give your entity new abilities.
• createToolExecutor() maps tool names to handlers. Add the implementation here.

Adjust cycle timing, action budgets, and other parameters.

Ben stores memory as markdown files on disk. Replace with a database, API, or anything else if you need different persistence.

The default memory structure:

data/
├── journal.md         Timestamped thoughts and observations
├── relationships.md   Notes on people and agents
└── state.json         Last mood (carried between cycles)

Requires Node.js >= 20. No build step — just npm install and npm start.

MIT