yc-software/qm

Overview

QM (from YC Software) is an agent server for a whole company, not for one person. It runs as a headless TypeScript service. People talk to it from Slack or from its own web app. Each person, channel, team, group and the org itself is a scope (personal:, channel:, team:, group:, org: in src/types.ts). A scope owns its own memory notebook, files, keychain view, crons, published web apps and a durable sandbox computer. The design goal is that a personal assistant and a shared channel assistant can run on one deployment without leaking into each other.

QM does not ship its own agent loop. It wraps existing coding-agent harnesses, Pi (the default, via the vendored @earendil-works/pi-ai and pi-coding-agent packages), OpenCode, Codex and Claude Code. All four sit behind one Harness interface. Everything around the loop belongs to QM: the turn queue, the system prompt, memory capture, tool authorization, approvals, content screening, credentials and the sandbox. As a personal assistant, its standout feature is the built-in Inbox loop. It scans Gmail and Slack on a schedule and keeps a ledger of messages that wait for your reply, each with a draft in your voice.

This is a big codebase (about 2,400 files; src/core/orchestrator.ts alone is 4,666 lines). It is aimed at a startup that will run it in its own cloud account, with Postgres, and maintain a deployment repository for it. It is not a single-user desktop tool.

Architecture

flowchart LR
  SL["Slack plugin (Bolt)"] --> APP["app.turn()"]
  WEB["Web UI / admin (Lit)"] --> API["Fastify /v1/turns"]
  API --> APP
  APP --> Q["Run queue (Postgres runs)"]
  Q --> W["Worker: processRun"]
  W --> ORCH["Orchestrator.handleTurn"]
  ORCH --> MEM["Memory service + strategy"]
  ORCH --> TOOLS["Tool context + policy"]
  ORCH --> HR["Harness router"]
  HR --> H["Pi / OpenCode / Codex / Claude"]
  H --> LLM["Model catalog + providers"]
  TOOLS --> SBX["Per-scope sandbox"]
  ORCH --> TAPE["Session store / tape"]

Component	Path	Role
Entry point	src/index.ts, src/wiring.ts	Loads config, builds every service, runs migrations, starts the HTTP server, scheduler and Slack reconciler
HTTP API	src/api/	Fastify routes (routes/turns.ts, admin, connectors, loops, crons, webhooks) and app-turn.ts, which admits and enqueues turns
Run queue and workers	src/runs/	Postgres runs table with leases and heartbeats; worker.ts claims runs and calls the orchestrator
Orchestrator	src/core/orchestrator.ts, src/core/orchestrator/	Builds one turn: identity, scope, system prompt, memory recall, tools, approvals, screening, then dispatches to a harness
Harnesses	src/harness/	Harness contract, harness-router.ts, and adapters for Pi, OpenCode, Codex and Claude Code; agent-tools.ts defines the tool surface
Models	src/model/	Catalog, overlays, custom providers and gateway models; default agent model id claude-opus-5
Memory	src/memory/	Per-scope memory/MEMORY.md notebook with revisions, capture strategies, and optional external MCP providers
Policy and security	src/policy/, src/security/	Command policy regexes, security posture, the LLM content-screening classifier
Sandboxes	src/sandbox/	Sandbox interface with local (Docker), AWS microVM, Sprites, smolmachines, E2B, Modal, Porter, Agent37 and Superserve backends
Connectors and MCP	src/connectors/, src/credentials/, src/mcp/	OAuth providers, encrypted keychain, admin-registered MCP servers
Loops and crons	src/loops/, src/cron/	Background work: the Inbox loop, scheduled jobs, inbound webhooks
Slack	src/slack/	In-process Bolt plugin that turns events into core turns and renders approvals
Surfaces	plugins/	web-ui, admin, portal, auth, onboarding
CLI	cli/	qm init, check, plan, up for deployment directories (Docker, Fly, AWS backends)

How a request flows

Take a Slack mention: “@qm summarise my unread email”.

1. Startup. src/index.ts loads config, calls buildApp, runs the registered Postgres migrations, initialises sandbox resources, hydrates identity and custom providers, starts the run runtime and the HTTP server (src/index.ts).
2. Ingress. The Bolt plugin handles app_mention and message events in src/slack/events.ts. callCore submits the turn with async: true (src/slack/turn-flow.ts). The Slack plugin runs in-process, so submitTurn is a direct call to app.turn with surface: "slack" (src/api/slack-core-client.ts). The web UI reaches the same function over POST /v1/turns (src/api/routes/turns.ts).
3. Admission and enqueue. app.turn resolves the actor and refuses non-internal principals. It handles steering into an in-flight run, then calls runs.enqueue with the thread as the session id and an optional dedup key (src/api/app-turn.ts, src/api/app-turn.ts).
4. Claim. A worker claims the oldest pending run with FOR UPDATE SKIP LOCKED. It skips any run whose session already has a running or earlier pending sibling, so turns in one thread run strictly in order (src/runs/postgres-run-store.ts). processRun heartbeats the lease and cancels the turn if the lease is lost (src/runs/worker.ts).
5. Build the turn. Orchestrator.handleTurn checks access, takes a session turn lease, and resolves scope and sharing. It reads a memory snapshot (src/core/orchestrator.ts). It then assembles the system prompt from the mode frame, the resolved scope prompt, shared core instructions and the security-policy text (src/core/orchestrator.ts). Skills, cron, keychain and connected-app blocks are appended after that.
6. Tools. createToolContext binds the sandbox, the credential handles and the command policy for this scope (src/core/orchestrator.ts). A tool call that matches a require_approval rule throws NeedsApproval. A deny rule throws CommandDenied (src/tools/primitives.ts).
7. Recall and dispatch. Recalled memory goes into the turn’s environment note as a delta, so facts already visible in the history are not repeated (src/core/orchestrator.ts). Then deps.harness.turns.runTurn is called (src/core/orchestrator.ts). The router resolves the runtime choice, resets provider sessions if the thread switched harness, and wraps adapters that lack native goal enforcement (src/harness/harness-router.ts).
8. Finish. Entries go to the session store as the turn runs. On a pause for approval, the run ends with pausedOnApproval, and Slack renders an approval card. Otherwise the memory strategy’s onTurnEnd is queued for the scope (src/core/orchestrator.ts), and the worker marks the run complete.

Key components

Harness contract

Harness has four parts: an adapter profile (control transport, tool transport, capabilities such as steer, native-tape and goal-enforcement), turns.runTurn, a set of optional model utilities (oneShot, judge, screenSecurity, compactHistory, generateTitle), and tool-name presentation (src/harness/harness.ts). The utilities matter, because memory extraction, titles and security screening are all one-shot calls through the active harness. QM therefore needs no separate LLM client for them. HARNESS accepts mock, pi, opencode, codex or claude (src/config.ts).

Tool surface

The tool set is fixed and small. It is defined in src/harness/agent-tools.ts: execute, sandbox, read, write, skill, memory, history, subagents, sessions, background, cron, webhook, share, publish, attach, finish_silently and a few others. Most real work goes through execute, which runs shell commands in the scope’s sandbox. Connectors and skills are reached through that sandbox, not through hundreds of typed tools. Admin-registered MCP servers are the exception. Their tools are namespaced <serverId>_<toolName>, and every call is audited (src/mcp/mcp-tool-service.ts).

Memory

Memory is a Markdown bullet notebook per scope, memory/MEMORY.md (src/memory/memory-service.ts). Recall is capped at the last 6,000 characters (src/memory/memory-service.ts). With Postgres, every write is a row in memory_revisions, so history and restore come for free (src/memory/postgres-memory-service.ts). Capture is pluggable: per-turn (default), scratch-promote or agent-only (src/memory/strategy.ts). The default does not extract after every message. It buffers a “burst” of turns per scope, conversation and actor. It flushes after 3 minutes of quiet or 10 turns, then makes one extraction call with a strict provenance prompt: only facts the user stated, directives kept verbatim, no secrets (src/memory/strategies/per-turn.ts, src/memory/strategies/per-turn.ts). Retrieval is not vector-based. The prompt gets the tail of the notebook, and query is a keyword match over bullets.

Security posture and command policy

An org picks dangerous, auto or strict. Narrower scopes can only tighten it (src/security/security-posture.ts). strict sends every tool call to human approval, and auto blocks private networks. Content screening (off/observe/enforce) is a separate deployment setting, and dangerous caps it at observe. Independently of posture, a regex command policy applies everywhere. The org floor asks for approval on recursive rm, force-push, DROP/TRUNCATE TABLE and curl | sh, and hard-denies mkfs and fork bombs. Scope rules are appended, and an org allowlist cannot be loosened to a denylist (src/policy/command-policy.ts).

Sandboxes

The Sandbox interface covers provisioning from workspace layers, run, file I/O, staging blobs, long-running processes with stdin and signals, and home snapshots (src/sandbox/sandbox.ts). SANDBOX_BACKEND defaults to local, which uses docker exec. Eight other backends are accepted (src/config.ts). Some hosted backends run with open egress unless you configure an egress proxy, and config prints a warning when that happens.

Inbox loop

The Inbox loop is a recurring agent task (every 15 minutes by default). It scans Gmail and Slack for conversations where the last message waits on the user, investigates context, writes a draft reply in the user’s voice, and posts items to a ledger API. If nothing changed, the turn ends silently (src/loops/inbox-loop.ts).

Extending it

• Deployment directory. Org config, custom tools, skills, sandbox image and infrastructure live outside core, in a deployment repository that pins @yc-software/qm. The qm CLI validates and deploys it (check, plan, up).
• Skills. Skills are scope-owned folders, seeded from skills-seed/ (Gmail voice profile, morning digest, Google Workspace, Linear, publish and others). They can be shared by grant, promoted org-wide by an admin, or imported as packs from git (src/skills/).
• Models. Admins can register custom providers that speak OpenAI Chat Completions, OpenAI Responses or Anthropic Messages at any http(s) base URL. That includes self-hosted endpoints. These models are reachable only through harnesses that route via pi-ai (src/model/custom-providers.ts).
• MCP servers. Admins (not end users, by design) register HTTP MCP servers with no auth, a bearer token or client-credentials auth.
• Memory providers. src/memory/provider-router.ts can route a scope kind to an external MCP memory provider and keep the built-in notebook.
• Harnesses. A new harness is a defineHarness(profile, implementation) call plus registration in wiring.

Running it

• Requirements. Node 24.15+, at least one model credential (Anthropic, OpenAI, OpenRouter, a Codex or Claude subscription credential, or a custom provider) and, for anything real, Postgres. Without SESSION_STORE=postgres and DATABASE_URL, sessions live in process memory and disappear on restart.
• Local development. npm start runs src/index.ts directly on Node, and npm run worker runs a separate worker. npm run dev-instance:web / :slack brings up a real-model, real-Postgres instance. The local sandbox backend needs Docker.
• Production. qm init --org <slug> --target <fly-or-aws> scaffolds a deployment repository. Deploy providers are docker, aws, fly and porter, with Helm charts under deploy/helm. Slack is optional: socket mode or HTTP events, with bot and app tokens. Published web apps need a wildcard DNS record.

Strengths and caveats

• Strength: real multi-tenancy. Scope-keyed memory, keychains, sandboxes and grants, plus an isolated default sharing posture, is the core of the design. Most personal-assistant projects never attempt this.
• Strength: durable execution. Turns are Postgres runs with leases, heartbeats, per-session ordering and crash-loop parking. A dead worker does not lose a conversation.
• Strength: layered safety. Posture, regex command policy, human approvals with session/always grants, an LLM injection screen over tool results, and audit sinks for egress and credential use all work together.
• Strength: harness and sandbox portability. You can swap Pi, Codex, OpenCode or Claude Code, and nine sandbox backends, without changing the surrounding product.
• Caveat: weight. It needs Postgres, a sandbox backend, OAuth app registrations and a deployment repository. The orchestrator is one 4,600-line closure, which makes it hard to read and to fork.
• Caveat: simple memory. Memory is a flat bullet list with tail recall and keyword search. There are no embeddings, so large notebooks lose their oldest facts from the prompt.
• Caveat: shell-first integrations. Most connectors are used by the agent through execute and skills in the sandbox. This is flexible, but it costs more turns and tokens than typed tools.
• Caveat: contributions are text-only. The project accepts design notes in adrs/, not code PRs.

Sources: code at 23af31b, deepwiki-open wiki (20 pages), OpenDeepWiki wiki (35 pages), verified Q&A.