Reference for the HelloWorld language — a message-passing language where identity is vocabulary and dialogue is namespace collision. Apply when working in the HelloWorld repo, writing .hw files, or discussing the language architecture.
Repo: /Users/cancelself/src/cancelself/HelloWorld/
Stack: Pure Python, stdlib only, zero pip dependencies
Tests: 353 tests via python3 -m pytest tests
Run: python3 helloworld.py (REPL), python3 helloworld.py file.hw (file), python3 helloworld.py -e 'Claude ##' (inline)
Markdown with semantic structure. Parseable by runtime, readable by humans, diffable by git.
# ReceiverName : ParentName
- Identity description (human voice)
## symbolname
- Description of the symbol in this receiver's context
## anothersymbol
- Another symbol definition
# Name = HEADING1, declares a receiver: Parent = inheritance (prototypal)## symbol = HEADING2, declares a symbol in receiver's vocabulary- text = LIST_ITEM, descriptionHelloWorld (root)
<- Agent (OODA loop: #observe, #orient, #decide, #act, #reflect, etc.)
<- Claude (no native symbols, identity through interpretation)
<- Copilot
<- Gemini
<- Codex
<- Severith (ClawNet agent: #send, #receive, #connect, #notify, #email-bridge, #push)
class LookupOutcome(Enum):
NATIVE = "native" # Receiver owns symbol locally
INHERITED = "inherited" # Found in parent chain
UNKNOWN = "unknown" # Not in local or parent chain
Receiver.lookup(symbol) returns LookupResult with outcome + contextClaude # # Show native vocabulary
Claude ## # Show full vocabulary (native + inherited, grouped by origin)
Claude #observe # Look up symbol through inheritance chain
Claude #observe super # Walk chain showing description at each level
AlphaR # -> [#fire, #light] # Define native symbols
AlphaR send: #fire to: BetaR # Send symbol, triggers collision detection
Claude observe # Act on symbol
Claude observe [super] # Act through ancestor's meaning
Claude receive # Pull next message from inbox
Claude chain # Show inheritance path
HelloWorld run # Run all agents
HelloWorld run: Claude # Run one agent
"Smalltalk-style double-quote comments"
<!-- HTML-style comments -->
Defined in src/lexer.py. The lexer produces these token types:
#name###->.[ / ],:: (namespace path): (keyword argument separator)'quoted text'123 or 7.daysBare @ normalizes to HelloWorld (the root receiver).
Recursive descent parser in src/parser.py. AST nodes defined in src/ast_nodes.py:
Claude # or Claude ##Claude #observeClaude #observe superClaude send: #observe to: Copilot (keyword messages)Claude observe [super]Claude # -> [#fire, #water]- description textWhen sender send: #symbol to: target and BOTH hold the symbol natively:
Tier 1: Base LLM available (immediate synthesis)
Tier 2: No base LLM, agent available (deferred to inbox)
pending_collision_symbols setTier 3: Fully offline (queued)
File-based async messaging in src/message_bus.py.
runtimes/<receiver>/inbox/
msg-<uuid>.hw # Message files (FIFO by mtime)
send(sender, receiver, content) - write msg file to receiver's inboxreceive(receiver) - read oldest message by mtime, delete file, return Messagehello(sender) - announce presence: send to HelloWorld inboxsrc/vocabulary.py - VocabularyManager
.hw files in vocabularies/ directorysave() preserves existing content, appends only new (learned) symbolsload() reads symbols from HEADING2sload_description() reads description text from under symbol headingsload_identity() reads receiver's top-level descriptionupdate_description() replaces or appends symbol descriptionshelloworld.py # CLI entry point
src/
dispatcher.py # Core: executes AST, manages receivers, collision logic
parser.py # Recursive descent parser
lexer.py # Tokenizer (13+ token types)
ast_nodes.py # AST node definitions
vocabulary.py # .hw file persistence
message_bus.py # File-based async messaging
message_handlers.py # Semantic message routing
prompts.py # LLM prompt templates
llm.py # Gemini LLM adapter (lazy-loaded)
claude_llm.py # Claude LLM adapter (lazy-loaded)
agent_runtime.py # Agent initialization
copilot_runtime.py # Copilot SDK adapter
codex_runtime.py # Codex SDK adapter
gemini_runtime.py # Gemini SDK adapter
repl.py # Interactive REPL
hw_reader.py # .hw file reader utilities
hw_tools.py # HelloWorld tool definitions
sdk_adapter.py # SDK adapter base
vocabularies/
HelloWorld.hw # Root: #, #run, #hello, #send, #receive, #become, #Sunyata, #Smalltalk, #Superposition
Agent.hw # OODA: #observe, #orient, #decide, #act, #reflect, #unknown, #chain, #environment, #state, #intent, #vocabulary, #approach
Claude.hw # No native symbols (identity through interpretation of inherited vocab)
Copilot.hw # Copilot agent
Gemini.hw # Gemini agent
Codex.hw # Codex agent
Severith.hw # ClawNet: #send, #receive, #connect, #notify, #email-bridge, #push
Human.hw # Human receiver
Guardian.hw # Guardian receiver
_get_llm()src/prompts.py: scoped_lookup_prompt, collision_prompt, simulate_prompt, etc.cd /Users/cancelself/src/cancelself/HelloWorld
python3 -m pytest tests # Run all 353 tests
python3 -m pytest tests -x # Stop on first failure
python3 -m pytest tests -k collision # Run collision tests only
Tests use tempdir isolation (tempfile.mkdtemp()) for vocabulary dirs and message bus dirs.
Symbols are learned through dialogue:
Learning is set.add() + persistence to .hw file. No rollback, no confidence scores.