Geode Serve

geode serve — Slack Gateway Operations Guide

Source: Distilled from Gateway debugging session (2026-03-26) Primary failure modes: missing binding, missing xapp- token, or bot not invited to a bound channel

Diagnosing a connection does not authorize credential changes, channel messages, or process restarts. Apply only the requested operation and keep credential values, fragments, and private message content out of reports.

Architecture

geode serve
  → core/wiring/adapters.py: Merge ~/.geode/config.toml + project overlay
  → SlackPoller: SLACK_APP_TOKEN present → SlackSocketModeClient.run()
  → bounded-queue admit → ACK Events API envelope → filter exact bound channel → route_message()
  → _send_response(): SlackTransport.post_message (direct Web API, thread reply)

No `SLACK_APP_TOKEN` selects an explicit degraded polling fallback. It is a
migration path, not the operational target.

Prerequisites

The shell presence checks cover inherited environment variables only. An unset variable does not prove the runtime lacks a credential: the resolver also uses the global .env. Do not print or copy that file to investigate.

geode doctor slack makes live Slack calls (auth.test, apps.connections.open, and channel membership checks). Its credential rows use partial masking, not full redaction; workspace/bot identifiers also appear. Keep raw diagnostics local and report only check names, status, and redacted findings. The temporary Socket Mode URL is omitted from the successful diagnostic report.

config.toml Setup

Use .geode/config.toml.example to create a project config only when none exists. If it already exists, edit the required binding fields in place and preserve unrelated settings. Never overwrite an existing global config or project overlay with the template.

[gateway.bindings]

[[gateway.bindings.rules]]
channel = "slack"
channel_id = "C0XXXXXXXXX"  # Slack channel → Click channel name → Channel ID at bottom
auto_respond = true
require_mention = true       # true: respond only on @mention
time_budget_s = 90           # optional per-message override; otherwise inherit gateway budget

• config.toml is in .gitignore — not deleted by git pull
• config.toml.example is committed — reference for clean clones
• Adding channels: Repeat [[gateway.bindings.rules]] blocks

Start/Restart

Follow Rebuild & Restart only when startup or restart is authorized. Confirm the installation, GEODE home/socket, PID, and session owner before stopping anything. The lifecycle implementation in core/cli/commands/lifecycle.py currently discovers the first matching serve PID; neither that match nor the stop command proves ownership. If several sessions match or ownership is unclear, stop and request direction.

Restart the confirmed installation through its existing launcher and retain startup diagnostics. Do not replace a managed service with an unrelated background process or discard its logs into /dev/null. Verify the requested process and socket before claiming it restarted.

Debugging Checklist

Symptom: Bot does not respond to messages

# 1. Identify the intended process/socket without stopping it (see Start/Restart).

# 2. Verify binding load
grep "binding" ~/.geode/logs/serve.log
# Expected: "Loaded N gateway bindings from config"
# If 0 → config.toml missing or parse error

# 3. Verify config source and Socket Mode
grep -i "gateway config sources" ~/.geode/logs/serve.log
# Expected: "Gateway config sources: global:... [, project:...]"

grep -E "Slack inbound mode|Slack Socket Mode connected" ~/.geode/logs/serve.log
# Expected: Socket Mode (push), then connected

# 4. Only when live Slack diagnostics are authorized; do not publish raw output.
geode doctor slack

# 5. Verify message reception after an @geode mention
grep "Slack message from" ~/.geode/logs/serve.log

Symptoms and Causes

Reaction Behavior

require_mention = true + first <@BOT_ID> mention:

1. :eyes: reaction (acknowledge receipt)
2. Normalize the root ts as thread_id and remember the engaged thread
3. ChannelManager.aroute_message() → AgenticLoop execution
4. :white_check_mark: reaction (complete)
5. Send response in thread

Later human reply in that engaged thread (no repeated mention):

1. Match channel-scoped engaged state or the durable ACTIVE/PAUSED gateway checkpoint
2. Reuse the same session/lane/checkpoint key and restore checkpoint messages after restart
3. Run the same :eyes: → AgenticLoop → :white_check_mark: → thread-response lifecycle

Unengaged regular message (no mention, require_mention = false):

• Process without reaction + thread response

Related Files