spacebot

The Problem

Most AI‑agent frameworks run everything in a single LLM loop – conversation, thinking, tool execution, memory retrieval and compaction all share one thread. When the agent is working it cannot respond; when it is compacting it goes dark. In multi‑user spaces (Discord, Slack, Telegram) a single‑threaded session becomes a bottleneck the moment two people speak at once.

Spacebot sidesteps this by splitting the monolith into specialized processes that each do one thing and delegate the rest. The architecture was built from the ground up for teams and communities that need concurrent, non‑blocking interactions.

What This Does

Spacebot is an AI‑agent runtime composed of three projects inside the repo:

Key architectural pieces:

• src/agent/compactor.rs – handles context compaction without blocking the conversation thread.
• src/api/server.rs – thin HTTP gateway that forwards requests to the appropriate worker process.
• interface/src/ui/utils.tsx – hub module imported by 30 other UI modules; any change here has a high‑blast‑radius.
• interface/src/ui/utils.tsx and interface/src/ui/index.ts are the primary entry points for the React/Next.js front‑end (see interface/index.html and interface/src/App.tsx).

The system uses a delegation model: a lightweight “router” process receives a user message, looks up the appropriate worker (code execution, web search, file I/O), hands the work off, and immediately returns control to the UI so other users can continue. This lets fifty people interact simultaneously without each waiting for the LLM to finish.

How It Is Wired

Internal call graph – 85 modules, 77 import edges, zero circular dependencies.

Entry → execution flow

1. User sends a message through Discord/Slack/Telegram → the platform’s webhook hits interface/src/hooks/useEventSource.ts (source‑event handling).
2. The hook forwards the payload to interface/src/router.tsx, which decides the agent route (e.g., AgentCortex, AgentMemories).
3. interface/src/routes/AgentCortex.tsx (or the memories route) calls src/api/server.rs (/api/run) to spawn a worker process.
4. The worker runs the requested tool (code execution, browser, etc.) and returns results through the same API.
5. Results are stored in the internal DB (migrations under migrations/) and fed back into the conversation context via src/agent/compactor.rs.

Most connected modules (Ca = importers, Ce = imports, instability = Ca/Ce ratio):

The hub interface/src/ui/utils.tsx is imported by 30 UI components; any modification ripples across the whole front‑end, which is why the measured findings flag it for “keep stable and small; move volatile logic out.”

What the code touches outside the repo

• Docker image (Dockerfile) builds a rust:bookworm + debian:bookworm-slim base, runs the binary as root (no USER directive – see code‑health audit).
• GitHub Actions workflows (.github/workflows/) use mutable Action versions (@v3, @v6) and have no test invocation.
• No Dependabot/ Renovate config is present.

How To Use It

Setup

# Clone the repository (verbatim URL)
git clone https://github.com/moses-y/spacebot

# Install Rust toolchain (if not present)
rustup default stable

# Build the binary
cargo build --release -p spacebot   # from repo root

Configuration

Required environment variables are defined in interface/src/lib/providerIcons.tsx and read by the UI forms. The README lists the following keys (exact names may vary – check the file):

• DISCORD_TOKEN, SLACK_BOT_TOKEN, TELEGRAM_BOT_TOKEN
• DATABASE_URL (PostgreSQL‑compatible)
• OPENAI_API_KEY (or whichever LLM provider the agent uses)

Place these in a .env file at the repo root or export them before running the binary.

Running it

# Start the Rust backend (binary from cargo build)
./target/release/spacebot

# In a separate terminal, launch the Next.js UI
cd interface
npm install && npm run dev   # defaults to http://localhost:3000

The UI becomes reachable at http://localhost:3000; use it to create a new agent, attach a Discord/Slack/Telegram token, and invite the bot to your server.

Real‑World Use

A community admin drops Spacebot into a 200‑member Discord server.

• Five users ask code‑review questions in separate threads.
• Two users trigger a background research task (browser tool) while three others chat casually.
• The router (interface/src/router.tsx) dispatches each request to its own worker; the LLM never blocks, and the UI stays responsive.
• After the research task finishes, the compactor (src/agent/compactor.rs) trims the context and the bot replies with a concise answer, all while other conversations continue uninterrupted.

Code Health & Issues

Measured findings (static analysis, 86 total):

• [HIGH/clarity] Hub module – interface/src/ui/utils.tsx is depended on by 30 modules; high‑blast‑radius churn.
• [HIGH/cognitive_load] Deep nesting x55 – max indentation depth 8 in interface/src/ui/NumberStepper.tsx, interface/src/ui/ToggleGroup.tsx, src/agent/compactor.rs.
• [HIGH/clarity] Duplicated code blocks – 168 repeated 6‑line blocks across 35 files, e.g., interface/src/components/ChannelCard.tsx, interface/src/routes/Overview.tsx.
• [HIGH/cognitive_load] Oversized file x3 – src/api/server.rs, src/config.rs, interface/src/routes/Settings.tsx each exceed 3 500 lines.

Code‑health audit (8 findings, 0 critical):

• HIGH – Pin third‑party GitHub Actions to commit SHAs (.github/workflows uses @v3, @v6, etc.).
• HIGH – Make CI invoke the test suite it has (4 test files, no test command in any workflow).
• MEDIUM – Enable Dependabot or Renovate (3 manifests, no update bot).
• MEDIUM – Pin container base image by digest (Dockerfile uses rust:bookworm, debian:bookworm-slim).
• MEDIUM – Gate pull requests on a dependency vulnerability scan (absent from CI).
• MEDIUM – Add a non‑root USER to the Docker image (no USER directive).
• LOW – Set timeout-minutes on workflow jobs (release.yml has no job timeout).
• LOW – Add convention files (missing .editorconfig, .gitattributes, formatter config).

Committed secrets – src/secrets.rs contains path‑shaped placeholders; the health audit confirms they are present and should be rotated/removed.

The Bottom Line

Spacebot delivers a genuinely multi‑user AI‑agent experience by splitting work into independent processes, which is rare in the current landscape. The Rust core and TypeScript UI are well‑structured, but the codebase suffers from a high‑impact hub, deep nesting, duplicated logic, and oversized files that raise maintenance risk. Security hygiene also needs attention (action pinning, image digest pinning, test invocation, Dependabot).

Who should use it: teams or communities that need concurrent AI assistance across chat platforms and are comfortable investing in the outlined hygiene fixes. If you need a single‑user, turnkey bot with minimal ops overhead, another framework may be simpler; for multi‑agent, multi‑channel deployments Spacebot is a solid, if imperfect, choice.