Improving OM1 onboarding experience for first-time contributors (Beginner feedback & suggestions)

[Disaster7r]

Hello OM1 team and community 👋

First of all, thank you for building and open-sourcing OM1. The project is ambitious, well-structured, and clearly designed for serious robotics and multimodal agent development.

I’m sharing this discussion as constructive feedback from a first-time contributor, with the goal of improving the onboarding experience for new developers while fully respecting existing contribution guidelines.**

I recently set up OM1 locally (Linux / WSL environment) by following the documentation and repository instructions. Overall, the setup works well, but there are a few points where beginners may feel confused or stuck especially those coming from traditional Python workflows.

This thread is not a complaint, but a collection of observations and suggestions that may help future contributors get started faster and more confidently.

🔍 Observations During Setup
1. Dependency Installation Confusion

Many Python projects use requirements.txt, but OM1 correctly uses a modern setup with:

• pyproject.toml

• uv

• uv.lock

As a beginner, it’s easy to instinctively try:

pip install -r requirements.txt
which results in an error because the file doesn’t exist.

2. uv Usage Is Powerful but Under-explained

While uv sync works very well, new contributors may not immediately understand:

Why uv is used instead of pip

When to use uv sync vs uv run

Whether .venv needs manual activation or not

3. First Successful Run Is a Big Milestone

Once conversation or spot agents run successfully, everything starts to “click.”
However, the steps to reach that moment could be made more explicit.

💡 Suggestions for Improvement
✅ 1. Add a “Zero-to-First-Run” Section

A short section in README or Docs covering:

• Clone repo

• Initialize submodules

• uv sync

• Add API key

• Run first agent

This could be a 5–10 minute quick start for beginners.

✅ 2. Explicitly Call Out “No requirements.txt”

A small note like:

“OM1 does not use requirements.txt. Please use uv sync.”

This alone would prevent a very common beginner mistake.

✅ 3. Beginner-Friendly Logging Mode

On first run, logs can feel overwhelming.

Suggestion:

• A default or optional minimal logging mode

• Or a documented env flag like:

OM_LOG_LEVEL=MINIMAL
This would improve the first-time experience without reducing debug power.

### ✅ 4. Known Issues for WSL / Windows Users

A short doc or wiki section listing:

• Camera/audio limitations

• Permission notes

• Recommended workarounds (Docker, native Linux, etc.)

### 🤝 Why This Matters

• Improving onboarding:

• Reduces repeated setup questions

• Helps contributors reach meaningful work faster

• Improves contribution quality

• Encourages long-term community participation

I’m happy to help further by:

• Testing docs

• Improving beginner instructions

• Contributing small documentation PRs if useful

Thank you for maintaining a professional and welcoming open-source community 🙏
Looking forward to learning and contributing more.

— A new OM1 contributor
Disaster7r

[Prachi1615]

Hi @Disaster7r
Thanks foe your comments.
The additions you mentioned are pretty much covered in our docs including uv setup and logging. If you follow the docs correctly, you won't run into issues.
https://docs.openmind.org/developing/1_get-started
Follow this link to get more details.

Regarding windows/wsl setup, we'll be updating the docs shortly.
LEt me know if there's anything else we can help with.