mindroom: Instructions file for Codex

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.