Imported from jamesc/beamtalk (examples/chat-room/AGENTS.md). Install upstream with npx skills add jamesc/beamtalk --skill chat-room. Copyright stays with the author.

chat-room — Agent Guide

Multi-actor example: actors, inheritance, collections, and message passing.

Workspace Structure

chat-room/
├── beamtalk.toml        # Package manifest
├── src/
│   ├── message.bt           # Message value type (immutable)
│   ├── chat_room.bt         # ChatRoom actor (Set of members, history)
│   ├── chat_member.bt       # ChatMember actor (name, inbox, room)
│   └── moderator.bt         # Moderator actor (inherits ChatMember)
├── test/                # BUnit tests (add your own)
├── AGENTS.md            # This file
├── .mcp.json            # MCP server config
├── .github/
│   └── copilot-instructions.md
└── .gitignore

Starting the REPL

cd examples/chat-room
beamtalk repl

All source files in src/ load automatically when you start the REPL. To run the tests: :load "test/"

Key Concepts

• Value types — Message is an Object subclass (not an actor), created with new:
• Actors — ChatRoom, ChatMember, Moderator each run as BEAM processes
• Inheritance — Moderator extends ChatMember with super calls
• Collections — Set for member tracking, List for message history
• Blocks — do: iteration for broadcasting messages

Development Workflow

The .mcp.json MCP server provides a persistent REPL session. Use it as your primary development environment — not CLI commands.

Session startup:

1. Call describe to discover available operations
2. Call load_project with include_tests: true to load all source + tests
3. On a new codebase, read the language guide at https://www.beamtalk.dev/docs/language-features

Edit → Reload → Test → Debug loop:

1. Edit a .bt source file
2. evaluate: 'Workspace load: "path"' or evaluate: "ClassName reload" — or load_project again after multi-file edits
3. test with class name or file path — fast, no recompile
4. evaluate to debug failures — bindings preserved from prior calls
5. Only use CLI beamtalk test as a final full-suite check before committing

Live Workspace (MCP)

The .mcp.json in this project configures the beamtalk MCP server, which gives you live access to a running REPL. Claude Code starts it automatically via beamtalk-mcp --start — no manual beamtalk repl required.

Prefer MCP tools over guessing. If you're uncertain what a method returns or whether code is correct, evaluate it directly rather than inferring from source.

Essential Patterns

Class Hierarchy

// Immutable data — auto-generates getters, withX: setters, keyword constructor, equality
Value subclass: Point
  state: x = 0
  state: y = 0

// Mutable state — manual getters/setters, self.field := works
Object subclass: Config
  state: raw = nil

// Concurrent process — gen_server backed, async casts with !
Actor subclass: Server
  state: count = 0

// OTP supervision tree — for long-running services
Supervisor subclass: MyApp
  class strategy => #oneForOne
  class children => #(DatabasePool, HttpServer, Worker)

Rules:

• Pure data → Value
• Mutable but not concurrent → Object
• Concurrent process → Actor
• Long-running service with child processes → Supervisor with beamtalk run

String Escaping

Destructuring and match:

// Tuple destructuring (critical for Erlang FFI)
{#ok, content} := Erlang file read_file: "path"

// Array destructuring
#[a, b] := #[10, 20]

// Map destructuring
#{#x => x, #y => y} := someDict

// match: with clauses
value match: [
  #ok -> "success";
  #error -> "failure";
  _ -> "unknown"
]

Key Stdlib Classes

Critical Gotcha — Block Mutations

// WRONG on Value/Object — assignment inside block doesn't propagate
count := 0
items do: [:x | count := count + 1]  // count is still 0!

// CORRECT — use inject:into:
count := items inject: 0 into: [:acc :x | acc + 1]

Not Smalltalk — Common Pitfalls

Beamtalk looks like Smalltalk but has important differences. The compiler will catch most of these, but they waste time:

Implicit return rule: the last expression of a method body is always its return value. Never write ^ on the last line — only use it for early exits inside the method:

// Correct use of ^ for early return
safeDiv: other =>
  other = 0 ifTrue: [^0].
  self / other

Language Documentation

• Full language reference: https://www.beamtalk.dev/docs/language-features — read this when starting work on a new Beamtalk codebase
• Syntax rationale: https://www.beamtalk.dev/docs/syntax-rationale
• Examples: see files in this directory