The Problem

Teams that want a shared AI assistant often end up with a single monolithic bot that cannot keep individual workspaces separate, nor can it scale across Slack, web UI, and custom internal tools. Managing per‑user state, permissions, and extensible “skills” becomes a maintenance burden.

What This Does

qm is a portfolio of six loosely‑coupled projects that together provide a multiplayer agent harness.

  • Core runtime – src/ (≈340 TS files) implements the headless engine, API, orchestration, and wiring (src/wiring.ts, src/types.ts).
  • Plugins – plugins/ hosts self‑contained extensions such as the admin UI (plugins/admin/src/index.ts), Slack integration (plugins/auth/src/server.ts), and other optional front‑ends.
  • CLI – cli/src/cli.ts (exposed as cli/bin/qm.ts) validates deployment directories, builds Docker images, and drives infra commands (cli/src/commands/*).
  • Deploy scripts – deploy/ and aws/ contain Dockerfiles and Terraform snippets for production deployment.
  • Skill seeds – skills‑seed/ supplies example skill packages that can be imported into a deployment.

All projects share the same TypeScript codebase, npm lockfiles, and Docker build pipeline.

How It Is Wired

Execution starts at cli/bin/qm.ts, which loads cli/src/cli.ts. The CLI parses sub‑commands (e.g., init, infra, sandbox) and then calls the central wiring layer src/wiring.ts.

src/wiring.ts imports the hub module src/types.ts (352 incoming imports, the most connected module). This hub defines shared type definitions and configuration interfaces used across the entire codebase, making any change high‑impact.

From the wiring layer the flow proceeds to:

  1. API server – src/api/server.ts creates a Fastify instance, registers routes, and attaches the orchestrator (src/core/orchestrator.ts).
  2. Orchestrator – coordinates a turn by invoking the selected harness (Pi, OpenCode, Claude Code) and interacts with the per‑scope sandbox (src/harness/pi-harness.ts).
  3. Persistence – src/persistence/durable-map.ts and the Postgres layer (src/db/*) store session history, memory, and queues.

Plugins mount onto the API via their own entry points (plugins/admin/src/index.ts, plugins/auth/src/server.ts). They import the same wiring and types, thus sharing the hub’s blast radius.

The static import graph shows 74 modules in circular dependencies; the most prominent cycles involve src/types.ts, src/config.ts, and src/auth/capability-token.ts. These cycles increase change risk because a modification may require coordinated updates across multiple files.

How To Use It

# Clone and install
git clone https://github.com/moses-y/qm
cd qm
npm ci            # installs root and cli dependencies from package-lock.json

# Inspect the example environment
cp .env.example .env   # populate required DB and AWS vars per the file

# Validate a deployment directory (example: ./deploy)
node cli/bin/qm.js check ./deploy

# Build the admin Docker image
node cli/bin/qm.js infra build admin

The CLI commands (check, infra, sandbox, etc.) are defined in cli/src/commands/. Docker images are built from the Dockerfiles under aws/ and deploy/. No additional build scripts are required.

Real‑World Use

A startup can run qm as a service behind a Postgres instance. Each employee logs into the web UI; the core API creates a sandbox image per user, loads the employee’s credentials, and runs scheduled “crons” that pull data from internal databases. Slack messages are processed by the plugins/auth Bolt server, which forwards them to the same core turn loop, guaranteeing identical behavior across channels and the UI.

Code Health & Issues

  • HIGH – Import cycles (16 files) – e.g., src/types.ts, src/config.ts. Break cycles by extracting shared types.
  • HIGH – Hub module (src/types.ts) – 352 dependents; keep it stable, move volatile logic elsewhere.
  • HIGH – Oversized files – src/wiring.ts (1,415 lines). Split by responsibility.
  • MEDIUM – High branching density – src/api/server.ts, src/auth/capability-token.ts. Refactor to strategy tables or smaller functions.
  • MEDIUM – Deep nesting – src/core/orchestrator.ts. Flatten with guard clauses.

Repository Hygiene

  • Tests present (556 files) – CI runs via GitHub Actions (.github/workflows/*).
  • Dockerfiles exist for core services.
  • LICENSE and lockfiles are committed.
  • Committed secrets detected in cli/src/secrets.ts and related tests – must be removed.

Code‑Health Audit Findings

  • MEDIUM – Least‑privilege GITHUB_TOKEN not declared (.github/workflows/cicd.yml).
  • MEDIUM – No Dependabot/Renovate configuration.
  • MEDIUM – No dependency‑vulnerability scan in CI.
  • MEDIUM – Docker images run as root (aws/microvm-agent/Dockerfile).
  • LOW – Missing timeout-minutes on workflow jobs.

Apply the fixes as described in each finding; they are the only recommended changes.

The Bottom Line

qm delivers a modular, multi‑user AI assistant platform with clear separation of core, plugins, and deployment artifacts. Its strong test coverage and CI are positives, but the codebase suffers from a large hub module, import cycles, and several security‑related hygiene issues that should be addressed before production use. Engineers comfortable refactoring TypeScript and managing containerized deployments will find it a solid foundation for building collaborative AI tools.