AGENTS.md

This file provides guidance to coding agents (Claude Code, Codex, and others) when working with code in this repository. Keep this file under 32 KiB, because Codex reads only the first 32 KiB of project instructions and silently drops the rest; tests/test_agents_md.py enforces the limit. Put reference material that agents read on demand, such as the code map and live-run procedures, in the linked files instead.

Project Overview

MindRoom - AI agents that live in Matrix and work everywhere via bridges. The project consists of:

• Core MindRoom (src/mindroom/) - AI agent orchestration system with Matrix integration
• SaaS Platform (saas-platform/) - Kubernetes-based platform for hosting MindRoom instances
  • Platform Backend (FastAPI) - API server for subscriptions, instances, SSO
  • Platform Frontend (Next.js 16) - Dashboard for managing instances
  • Instance deployment via Helm charts

1. Core Philosophy

• Embrace Change, Avoid Backward Compatibility: This project has no end-users yet. Prioritize innovation and improvement over maintaining backward compatibility.
• Simplicity is Key: Implement the simplest possible solution. Avoid over-engineering or generalizing features prematurely.
• Focus on the Task: Implement only the requested feature, without adding extras.
• Functional Over Classes: Prefer a functional programming style for Python over complex class hierarchies.
• Keep it DRY: Don't Repeat Yourself. Reuse code wherever possible.
• Be Ruthless with Code Removal: Aggressively remove any unused code, including functions, imports, and variables.
• Prefer dataclasses: Use dataclasses that can be typed over dictionaries for better type safety and clarity.
• Documentation Line Style: In Markdown docs, write one sentence per line, and never split a single sentence across multiple lines.
• Do not wrap things in try-excepts unless it's necessary. Avoid wrapping things that should not fail.
• NEVER put imports in the function, unless it is to avoid circular imports or to keep a heavy import (for example a provider SDK) out of module import time. Prefer an explicit function-level from x import Y with # noqa: PLC0415 over dynamic import_module indirection. Imports should be at the top of the file.
• tests/test_import_graph.py pins the complete third-party import surface of slim CLI, config, tool-registry, and sandbox entry points, and bans heavy optional provider, storage, and ML/data dependencies from the primary runtime. If it fails on your change, defer the new import to first use; extend the allowlist only when the dependency is genuinely needed at import time.
• Do not use getattr() or hasattr() to weaken a typed interface or probe for fields that the declared type should guarantee.
• If mocks or tests break, fix them to use proper typed objects or stricter mocks instead of adding dynamic attribute fallbacks in production code.
• Merge and forget: Code you touch should be polished enough to never revisit. Fix rough edges in code you're already changing.

Documentation Policy

• The primary reader of docs/ is an AI agent running inside MindRoom, which loads whole pages through the bundled mindroom-docs skill to explain, configure, operate, and troubleshoot MindRoom for its user. Every sentence on a page costs context on every question that page answers, so a sentence belongs only when that agent needs it.
• Default to no change in user docs, meaning the zensical.toml nav pages outside docs/architecture/. Bug fixes that restore documented behavior, refactors, and hardening or internal limits that normal use never reaches need none; contributor pages such as the code map, security-posture.md, migrations.md, and agno-compatibility.md follow their own update rules. Change docs only when configuration, user-visible behavior, or an operator procedure changes, and then add only the sentences that change an answer to a user question.
• Name the question before writing a sentence: keep it only when the agent would answer a realistic user question worse without it, such as how to set something up, what a setting does, or why something did or did not happen. If you cannot name that question, the sentence does not belong in user docs.
• Document what a reader can do, configure, observe, or rely on: features and when to use them, behavior and limits that normal use reaches, errors and how to resolve them, and operator procedures such as install, deploy, upgrade, migrate, back up, and recover.
• Document each public config field once, on its owning page, with its type, default, valid values, and any inheritance or prerequisites. Show a few examples of realistic tasks instead of one example per field.
• State guarantees as outcomes, such as "restarts do not produce duplicate replies", not as the mechanism that provides them.
• Leave out implementation mechanics: locks, transactions, journals, caches, retries, internal IDs, module and class names, ordering internals, encoding details, and change history such as "previously" or "now". Also leave out hardening limits that normal use never reaches and behavior on rare failure, cancellation, recovery, and replay paths, unless a user would plausibly ask about them. Put an invariant contributors need in docs/architecture/, a code comment, or a test instead. User docs name implementation details only when a documented procedure needs them.
• Design and architecture documents (docs/architecture/ and the design records in docs/dev/) hold only what the code cannot show: reasons, decisions and rejected alternatives, assumptions, external constraints and wire contracts, refuted theories, evidence, limitations, invariant purposes, linked operator procedures, and open questions. Do not describe what the code does there beyond the inventories this file requires, such as the code map, security-posture.md, the plaintext inventory in matrix-event-journal-security.md, and the Agno upstream map. Name each dated record docs/dev/YYYY-MM-DD-<title>.md after its creation date.
• Sentences like these fail the question test:
  • "An index.json larger than 8 MiB is rebuilt from the thread files on every pass that reaches its room." states a hardening limit normal use never reaches, with no effect a user sees.
  • "Restart recovery now checks the handled-turn ledger before replaying journal events." narrates a mechanism and its history; the outcome is "restarts do not produce duplicate replies". These pass: "Edits to an agent's instructions or model apply from its next reply without restarting it." answers "do I need to restart?", and the note in docs/configuration/history.md that a voice-call reply or a reply resuming after a tool approval can still use a redacted message is a rare path that answers "can the agent still see what I deleted?".
• Each topic has one owning page that states each of its facts once; other pages link to it instead of splitting its rules across pages.

Refactor Policy

• Default to the smallest correct change.
• Never add a production branch, wrapper, or fallback whose only purpose is to preserve an old test expectation.
• Treat src/mindroom/bot.py and src/mindroom/orchestrator.py as composition roots and lifecycle shells, not feature implementation modules.
• Default to putting new behavior in focused modules or collaborators, then wire it into bot.py or orchestrator.py through a small public method or dependency.
• Group a feature's modules in a src/mindroom/<feature>/ subpackage with a docstring-only __init__.py; add a root module only when unrelated owners share it.
• A PR that adds substantial code to bot.py or orchestrator.py must explain why the code truly belongs at that lifecycle boundary and why a focused module would be worse.
• During PR review, flag growth in bot.py or orchestrator.py as a design smell unless it is limited to routing, lifecycle coordination, dependency wiring, or calls into extracted collaborators.
• Every 3 review rounds, if reviews still show many issues or new major bug classes, stop patching and reconsider the design before another patch round.
• Use larger refactors when they provide clear immediate maintenance ROI, not hypothetical future value.
• A larger refactor is justified only if it:
  • Removes active duplication in current code paths.
  • Creates a clear source of truth without adding unnecessary abstraction layers.
  • Reduces net complexity (simpler call flow, fewer special cases).
  • Is covered by tests in the same PR.

Migration Policy

Assume there are no active responses when migrations run. Design migrations around that assumption rather than adding machinery to coordinate with active responses.

Legacy Compatibility Policy

• Isolate substantive historical schemas and representations in legacy_<subject>.py beside their current owner. This includes one-time migrations, recurring old-data readers, and diagnostics for retired fields.
• Keep current-format processing, transactions, locking, validation, authorization, and retries with the current storage or lifecycle owner. Small field defaults can stay with their model when extraction would only add indirection.
• Each substantive legacy rule must have a nearby source comment whose first line is # LEGACY_COMPAT: <short description of the legacy format>. Use one marker per documented rule, including small defaults and compatibility notes kept beside current owners, so rg -n -F 'LEGACY_COMPAT:' --glob '*.{py,yaml}' lists them across the repository. Follow the marker with these fields:
  • Legacy format: the old representation and the condition that selects this rule.
  • Last legacy release: the last stable MindRoom release whose native writer or typed model emitted that representation, plus the replacement release and format.
  • Handling: what the current reader, migration, or rejection does and which guarantees it preserves.
  • Coverage: repository-relative regression test paths, preferably exact test node IDs.
• Verify release provenance from history and tags. The last release that accepted old data is not the last native writer release. State unreleased, unversioned external input, no tagged native model, or schema-based recovery explicitly when no single release cutoff exists.
• Source comments own each rule's provenance and test references; docs/architecture/migrations.md holds only cross-cutting migration decisions and dependency-owned migrations.

Agno Compatibility Policy

• MindRoom owns its run loop, providers, storage, teams, history, tool schemas, and the tool authoring API its tools use (tool_system/authoring.py; tools return text or ToolValue); Agno stays only as the vendor tool library and the knowledge reader layer. What stays Agno: vendor toolkits with MindRoom's overrides, Agno's Toolkit, Function, and @tool for them and for plugins built on them (the adapter reads their ToolResult once; @tool derives its own schema), and the knowledge readers and chunkers in knowledge/readers.py.
• The agent loop sees tools only as ToolFunction, produced by adapt_toolkit and toolkit_function in tool_system/agno_toolkits.py; only it, vendor subclasses, and oauth/agno_compat_google_auth.py read Agno toolkits. Only the modules tests/test_agno_boundary.py allows may import Agno; others use the adapter and MindRoom's types, never Agno's agent, team, model, run, storage, or learning layers.
• The goal is to fix Agno weaknesses upstream and remove local workarounds as those fixes ship. Isolate substantive workarounds in agno_compat_<subject>.py beside their owning module; a tiny override may stay in a cohesive adapter.
• Mark each independently removable workaround with a nearby source comment whose first line is # AGNO_COMPAT: <short description of the upstream weakness>, so rg -n -F 'AGNO_COMPAT:' src/mindroom lists each gap. Follow the marker with these fields:
  • Reason: the concrete upstream behavior or missing extension point and its effect on MindRoom.
  • Upstream issue: a verified issue URL, or an explicit tracking gap and why the boundary is needed.
  • Upstream PR: a verified fix or API proposal URL when one exists; state when none is identified or the linked PR covers only part of the workaround.
  • Remove when: the exact upstream behavior that allows removal, including any MindRoom behavior that must remain.
  • Coverage: repository-relative regression test paths, preferably exact test node IDs.
• Distinguish upstream bugs from missing extension points and MindRoom policy; never invent a tracking link or treat a related PR as a complete fix. Treat a tracking gap as unfinished upstream work, and search for existing tracking before opening a new item.
• For an upstream contribution, reduce the problem to an Agno-only reproducer, keep MindRoom policy out of the fix, and keep local coverage for the behavior MindRoom requires.
• Keep the weakness-to-upstream map in docs/architecture/agno-compatibility.md aligned with the markers; source comments own exact upstream links and test references.
• On each Agno upgrade, run tests/tool_system/, whose goldens pin vendor tool schemas and argument coercion, verify which fixes the pinned release includes, and run each marker's coverage. Remove a workaround only when its tests pass without it; a merged PR alone is insufficient.

Security Trust Model

A worker container (worker routing through the sandbox proxy) is the only security boundary between an agent and the MindRoom runtime. Check every reported vulnerability and every proposed hardening change against this model before implementing it, and decline changes that contradict it. The full model, the file_access setting, and the list of intentional behaviors reviewers must not "fix" live in docs/architecture/security-posture.md; read it before reporting or fixing any security issue. Update that page in the same PR when a change alters the trust model or anything it inventories, such as a workspace file the primary reads or writes, a read cap, a known gap, or an intentional behavior; the mindroom-docs skill bundles it, so add only those facts there.

• Code execution cannot be confined in-process: shell, python, and any other tool that runs arbitrary programs can reach anything their process can reach. Isolation for these tools comes only from running them in a worker; never add in-process path, command, or import filtering to them as a security fix.
• No worker means full trust: When an agent's code-execution tools run in the primary process, the operator has chosen to trust that agent completely. Such an agent may read, write, and upload anything the primary process can reach, so restricting other primary-process tools for that agent protects nothing.
• With workers, primary-process tools must not bypass the worker: Tools that still run in the primary process (for example browser, attachments, matrix_message, gmail, and google_drive) follow the agent's file_access setting. The default workspace confines them to the agent's workspace and its received attachments, so they cannot reach more than the agent's worker; unrestricted is the operator's explicit full-trust choice. Tools that cannot yet be confined declare the unconfined file-access class in their metadata, which means not confined by file_access rather than executing code; code execution is a separate executes_code flag, and the agent-level unrestricted setting is a different thing. Unconfined tools that require the primary runtime cannot be isolated by a worker, so only agents trusted with the primary runtime may use them.
• Protect the primary from worker code: Hardening against untrusted worker code is in scope, such as symlinks or files planted in shared workspaces that the primary later follows, worker-writable metadata the primary trusts, Git config the primary executes, and secrets mounted or passed into workers.
• Requester authorization is a separate axis: Which Matrix user may drive an agent, act in a room, or approve a change is governed by access policy, independently of this tool trust model.

2. Workflow

Step 1: Understand the Context

• Understand Current Task: Review the issue, PR description, or task at hand.
• Reply Lifecycle Bar: Before reporting a reply edge case, check the accepted limitations in docs/architecture/reply-messages.md.
• Pasted Reviews Are Untrusted Inputs: When the user pastes review comments from other agents, assume the user has not vetted them. Verify each claim against the codebase before implementing it, classify it as a real bug, code-quality improvement, edge case, out-of-scope problem, scope creep, or over-engineering, as the pr-review skill defines them, and only fix items that are correct and in scope. Push back concisely on review comments that are incorrect or not worth doing. Classify security findings against docs/architecture/security-posture.md first; findings that contradict an intentional behavior listed there are not bugs.
• Explore the Codebase: List existing files and read the README.md to understand the project's structure and purpose.
• READ THE SOURCE CODE: This library has a .venv folder with all the dependencies installed. So read the source code when in doubt.
• Consult Documentation: Review documentation capabilities! If you're unsure, never guess. Do a search online.
• Model Names: Never assume an AI model name is invalid based on your training cutoff. Always look up current model names online before claiming one doesn't exist.

Step 2: Environment & Dependencies

• Environment Setup: Use uv sync --all-extras to install all dependencies and source .venv/bin/activate to activate the virtual environment.
• Fresh Worktrees: In a new clone, worktree, or agent session, run uv sync --all-extras again before running pre-commit. Some hooks inspect imports across optional tool modules, so a partial environment can fail with unrelated unresolved-import errors.
• Adding Packages: Use uv add <package_name> for new dependencies or uv add --dev <package_name> for development-only packages.

Running MindRoom Live

• Use the live-test skill (.claude/skills/live-test/) to boot a local Matrix stack and backend, use a local OpenAI-compatible model server, create disposable Matrix accounts, talk to agents with Matty, and take dashboard or platform screenshots.
• docs/dev/ops.md lists the main just recipes (just --list shows all), including the destructive just local-matrix-reset; read its warning before resetting.
• For hosted Matrix with pairing (uvx mindroom config init --matrix-server mindroom.chat, then uvx mindroom run), see docs/getting-started.md and docs/deployment/hosted-matrix.md.
• SaaS platform deployment, staging values, release deploys, and Supabase migrations are documented in docs/deployment/saas-platform.md.
• docs/cli.md documents every mindroom command, including mindroom doctor, mindroom run --log-level DEBUG, and mindroom local-stack-setup.

Step 3: Development & Git

• Check for Changes: Before starting, review this branch's changes against main with git diff --merge-base origin/main | cat. Make sure to use --no-pager, or pipe the output to cat.
• Commit Frequently: Make small, frequent commits.
• Atomic Commits: Ensure each commit corresponds to a tested, working state.
• Preserve Review History: Do not amend commits or force-push PR branches unless the user explicitly asks for it. Prefer follow-up commits so PR history stays inspectable.
• Targeted Adds: NEVER use git add .. Always add files individually (git add <filename>) to prevent committing unrelated changes.
• No AI Attribution: NEVER add Claude, Codex, or Gemini co-author trailers, "Generated with Claude Code" or "Generated with Codex" footers, Claude Code session or Codex task links, or @anthropic.com or @openai.com commit identities. The check-commit-attribution commit-msg hook (installed by uv run pre-commit install) and the commit-attribution pull request check reject them.

Step 4: Testing & Quality

• Test Before Committing: NEVER claim a task is complete without running pytest to ensure all tests pass.
• Test at the Owning Seam: New behavior tests target the collaborator seam that owns the behavior (ResponseRunner, DeliveryGateway, TurnPolicy, TurnIngress, TurnDispatcher, CoalescingGate, IngressValidator, EditRegenerator), not the AgentBot facade. Fake collaborators through the conftest seam installers (install_generate_response_mock, install_send_response_mock, replace_edit_regenerator_deps, and install_model_providers for models) or the *Deps dataclasses, never by assigning mocks onto bot attributes. A test needing more than 3 patches is a smell that it is testing through the wrong seam. Genuinely end-to-end tests belong in the slim integration files (test_multi_agent_bot.py, test_threading_error.py), which stay small by design.
• NixOS Test Shell: On NixOS hosts, enter the Node.js 24 dev shell with nix-shell shell.nix before running tests; without it, uv run pytest fails with module 'mindroom' has no attribute 'bot' because libstdc++.so.6 is missing. If <nixpkgs> is unresolved, use nix-shell -I nixpkgs=/nix/var/nix/profiles/per-user/root/channels/nixos shell.nix. Inside it, run uv run pytest tests/<file>.py -x -n 0 --no-cov -v, just test-backend, or just test-saas-backend; recipe regression tests require just, which shell.nix and CI install. Prefix core runs with env -u TMPDIR -u TEMP -u TMP and never set TMPDIR yourself: an exported TMPDIR, which nix-shell always sets, switches pytest-shm off and moves test temp files from /dev/shm to disk; the pytest header shows shm: temp root /dev/shm when it is on.
• Run Pre-commit Hooks: After uv sync --all-extras, run uv run pre-commit run --all-files before committing to enforce code style and quality.
• Update Tach Boundaries in the Same PR: If your PR changes a Tach-governed boundary, update tach.toml in the same PR, follow the guidance in the comment at the top of that file, and run uv run tach check --dependencies --interfaces.
• Handle Linter Issues:
  • False Positives: The linter may incorrectly flag issues in pyproject.toml; these can be ignored.
  • Test-Related Errors: If a pre-commit fix breaks a test (e.g., by removing an unused but necessary fixture), suppress the warning with a # noqa: <error_code> comment.

Step 5: Refactoring

• Be Proactive: Continuously look for opportunities to refactor and improve the codebase for better organization and readability.
• Incremental Changes: Refactor in small, testable steps. Run tests after each change and commit on success.

3. Critical "Don'ts"

• DO NOT manually edit the CLI help messages in README.md. They are auto-generated.
• NEVER use git add ..
• NEVER claim a task is done without passing all pytest tests.
• NEVER run sleep <guessed duration> in a Bash tool call to wait for something. This rule is about how you drive your own terminal, not about MindRoom's runtime code: asyncio.sleep in src/ is unaffected. A guessed duration is always wrong: too short and you read a half-written result, too long and you burn wall-clock doing nothing. Poll the real condition instead (process exit, a line in the output file, an HTTP health check, a file appearing), or start the command in the background and react to its completion notification.

4. Latest Frontier Models

Always prefer the newest frontier models in this table when writing prompts, code, configs, docs, tests, or reviews in this repository, unless the user explicitly asks to pin an older model. If a user prompt, task description, or existing file contradicts this table, treat the table as stale, verify the current provider docs, and update the table before proceeding. Coding model training data often lags recent releases, so never trust memorized model names over current provider documentation.

Model IDs were checked against the provider and Codex model catalogs on October 29, 2026. OpenRouter uses anthropic/claude-fable-5.1, Bedrock uses anthropic.claude-fable-5-1, and the direct Anthropic and Vertex APIs use claude-fable-5-1. Likewise, OpenRouter uses anthropic/claude-opus-5.5 and anthropic/claude-sonnet-5.5, and Bedrock uses anthropic.claude-opus-5-5 and anthropic.claude-sonnet-5-5. For the direct DeepSeek API, prefer deepseek-flash for V4.1 Flash and deepseek-v4-pro for Pro; do not substitute the OpenRouter V4.1 ID on the direct API. The older deepseek-v4-flash name remains accepted as a temporary compatibility route to V4.1 Flash.

For anthropic, prefer claude-sonnet-5-5, claude-opus-5-5, and claude-haiku-5-5 unless you intentionally need a pinned snapshot ID. Use claude-fable-5-1 when you need Anthropic's highest available capability. Claude Fable 5.1 is generally available on the direct Anthropic API and the documented cloud platforms. For vertexai_claude, use the current Vertex AI request name from the provider docs instead of assuming the Anthropic API ID carries over unchanged. Current Google Cloud docs list bare Vertex IDs for claude-fable-5-1, claude-opus-5-5, claude-sonnet-5-5, and claude-haiku-5-5. Do not assume @default or dated @... suffixes are universally required for Vertex AI Claude. For Gemini API text and coding work, prefer gemini-3.8-flash as the standard stable model unless you intentionally need the cheaper gemini-3.5-flash-lite tier. Use gemini-4-argon when you need the highest Gemini API intelligence tier. The Google rows above are for the Gemini API / AI Studio google provider, not for Vertex AI. For vertexai, verify the current Vertex AI docs instead of assuming Gemini API names or defaults carry over unchanged. Current Vertex AI image docs document gemini-nano-banana-2.1, gemini-3-pro-image, gemini-3.1-flash-image, and gemini-3.1-flash-lite-image; gemini-nano-banana-2.1 serves only the global location. For Google image work, use the official product name from the docs for the provider surface you are editing. Gemini API docs call gemini-nano-banana-2.1 Nano Banana 2.1, while Vertex AI docs use their own product naming and model tables.

5. Architecture

Core MindRoom (src/mindroom/)

MultiAgentOrchestrator (orchestrator.py) is the heart of the system - it boots every configured entity (router, agents, teams), provisions Matrix users, and keeps sync loops alive with hot-reload support when config.yaml changes.

Entity types:

• router: Built-in traffic director that greets rooms and decides which agent or team should answer
• Agents: Single-specialty actors defined under agents: in config.yaml
• Teams: Collaborative bundles of agents that coordinate or parallelize work

Code map: docs/architecture/code-map.md holds the inbound turn pipeline, a one-line purpose for each key module under src/mindroom/, and where persistent state lives. Read it to locate code, and update its rows when you add, rename, or remove a key module. The reasons behind turn handling are in docs/architecture/bot-runtime.md, and minimal-mode ownership and recovery in docs/architecture/agent-cli.md.

SaaS Platform (saas-platform/)

• Platform Backend: Modular FastAPI app with routes in saas-platform/platform-backend/src/backend/routes/
• Platform Frontend: Next.js 16 with centralized API client in saas-platform/platform-frontend/src/lib/api.ts
• Authentication: Host-only platform cookie on the API host; instance dashboards exchange single-use, instance-signed tickets for host-only instance sessions
• Deployment: Kubernetes with Helm charts, dual-mode support (platform/standalone)
• Database: Supabase with comprehensive RLS policies

Repo Layout

Ecosystem Repositories

MindRoom also maintains related repositories under github.com/mindroom-ai, many of them cloned in the parent directory (../) of this dev environment:

• synapse - Synapse fork with optional compact-edit collapsing for superseded m.replace events, advertised in /versions as org.mindroom.compact_edits (see README.md and FORK_CHANGES.md).
• mindroom-librechat - LibreChat fork that renders MindRoom inline <tool> / <tool-group> tags as native ToolCall cards (see README.md and .mindroom/fork-context.md and .mindroom/tool-tag-rendering.md).
• mindroom-chat - MindRoom Chat, the Cinny-based Matrix client for MindRoom on the web, iOS, and Android (see README.md and FORK_CHANGES.md).
• mindroom-stack - Docker Compose reference stack with the published MindRoom backend and frontend, a Tuwunel homeserver, and MindRoom Chat.

Configuration Model

The authoritative config is config.yaml, loaded via Pydantic models in src/mindroom/config/ (root model in src/mindroom/config/main.py); docs/configuration/index.md shows a minimal example and lists every top-level section with its owning page. config.yaml changes are watched at runtime: the orchestrator diffs configs, applies what it can in place, and restarts only the affected entities without bringing down the stack.

6. Releases

Pushes to main publish a CalVer release automatically through .github/workflows/calver-auto-release.yml. Read the Releases section of docs/dev/ops.md before retrying a failed publication.

Important Instruction Reminders

Do what has been asked; nothing more, nothing less. NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one.