Skip to main content

​
Prerequisites

  • Python 3.12+ — check with python3 --version
  • uv — install from docs.astral.sh/uv
  • git
  • Docker Desktop (optional) — needed for sandbox-related tests

​
Clone and install

1

Clone the repository

git clone https://github.com/gpuOS-ai/motus.git
cd motus
2

Install dependencies

uv sync --all-extras
uv sync --all-extras installs all dependencies including optional groups (dev, docs, test) in a local .venv.
3

Set up pre-commit hooks

uv run pre-commit install
This registers git hooks that run ruff (linting + formatting) on every commit. If ruff finds issues, the commit is blocked until you fix them. You can run the checks manually:
uv run pre-commit run --all-files
4

Verify setup

uv run pytest tests/unit/ -x -q
All unit tests should pass without any API keys or external services. If you see failures, check that you installed with --all-extras and are running Python 3.12+.

​
Editor setup

The ruff configuration lives in pyproject.toml under [tool.ruff]. Point your editor at this config to get consistent linting and formatting.
  1. Install the Ruff extension.
  2. The extension auto-detects pyproject.toml settings.
  3. Enable format-on-save for .py files:
{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true
  }
}

​
Running the docs locally

npx mintlify dev
Opens at http://localhost:3000. The site rebuilds on file changes.

​
Project layout

src/motus/
├── agent/          # Agent implementations (ReActAgent, etc.)
├── memory/         # Memory systems (CompactionMemory, etc.)
├── models/         # Model backends
├── runtime/        # Core runtime (AgentRuntime, AgentFuture, TaskInstance)
└── tools/          # Built-in tools

tests/
├── unit/           # Fast tests, no API keys
└── integration/    # VCR-based replay tests

​
Next steps

  • Read the Code Style guide for conventions beyond what ruff enforces.
  • Read the Testing guide before writing your first test.
  • Read the Pull Requests process when you are ready to submit.