Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Contributing to Dodaios
Dodaios is a cross-platform desktop application for voice, agents, and connected tools. We welcome focused fixes, tests, accessibility work, platform reports, and documentation improvements. The useful first step is a problem you can reproduce and explain; familiarity with the whole repository is not required.
Choose a first contribution
| Starting point | A useful, reviewable result |
|---|---|
| Open bugs | Confirm an issue still reproduces on current main, add a focused regression test, and fix it. Comment on the issue before starting if its scope is unclear. |
| Installation or product docs | Follow one documented path on a named OS, then correct the exact step that differs from reality. Include the command, observed result, and working replacement. |
| Desktop accessibility | Improve one keyboard, focus, or screen-reader interaction in dodaios/ui/web/frontend/src/. Show the before/after behavior in light and dark mode. |
| Platform parity | Test one existing feature on Windows, macOS, Linux, or a headless host, then submit a reproducible report or a narrow fix. Check OS parity first. |
Use GitHub Issues
for a concrete bug or task. For a larger design, use
Discussions to
agree on scope before implementing it. You can open a small, self-contained PR
without an issue. The good first issue label is used when a specific task has
been scoped. If that list is empty, pick an issue labeled help wanted or
area:docs, or propose a small task in Discussions.
Interested in helping maintain an area over time? Name the subsystem and the kind of testing or review you can provide in a Discussion. A series of scoped contributions gives everyone a concrete basis for deciding how to collaborate; repository owners handle review, merge, and access decisions.
Your first contribution in 10 minutes
Pick one path below based on what your issue needs. Both end with your fork ready and a passing check, so you know your setup works before you touch code.
Path A: a docs or frontend text change (Markdown, .md, .json locale files)
- Fork the repo and clone your fork.
- Find a task: browse issues labeled
good first issue. If none are open, pick any issue labeledhelp wantedorarea:docs, or ask in Discussions. Comment on it to claim it if you plan to start right away. - Make your edit directly in the file the issue points to. No install needed for a Markdown-only change.
- If the change touches
docs/, sanity-check it:python scripts/ci/check_public_docs.py - If the change touches
dodaios/ui/web/frontend/, install once and run the frontend tests:cd dodaios/ui/web/frontend npm install npm run test - Commit, push to your fork, and open a pull request. Use the
PR template; for a docs or one-view
change it only asks you to show the rendered result (a screenshot or the
check_public_docs.pyoutput is enough).
You do not need the Python backend running for this path.
Path B: a Python change (a fix, a new test, a small feature)
- Fork the repo and clone your fork.
- Find a task: browse issues labeled
good first issue. If none are open, pick any issue labeledhelp wantedorarea:docs, or ask in Discussions. Comment on it to claim it if you plan to start right away. - Set up once (Python 3.11+ and Git required):
python -m venv .venv # macOS/Linux: source .venv/bin/activate # Windows PowerShell: .\.venv\Scripts\Activate.ps1 python -m pip install -e . --no-deps python -m pip install -r requirements.txt python -m pip install -e ".[dev]" - Confirm setup worked before writing any code:
The printed path must point inside your cloned checkout. If it points somewhere else (e.g. a different Python install), yourpython -c "import dodaios; print(dodaios.__file__)"pip install -ewent to the wrong environment: re-checkpython -m venvpicked up the interpreter you expect. - Make your change, then run the focused test the issue names, e.g.:
pytest tests/path/to/relevant_test.py - Before opening the PR:
ruff check dodaios/ ruff format --check dodaios/ mypy dodaios/ - Commit, push to your fork, and open a pull request using the PR template. State which command you ran and that it passed.
You only need run-dev.bat (Windows) or ./run-dev.sh (macOS/Linux) if your
change needs to be seen running in the actual desktop app; most focused fixes
and new tests do not.
If you get stuck
Ask in Discord or on the issue itself; partial progress and questions are welcome, you do not need a finished PR to say hello.
Find your way around
| Area | Start here |
|---|---|
| Core contracts and events | dodaios/core/protocols.py, dodaios/core/events.py |
| Desktop and web UI | dodaios/ui/web/frontend/; backend routes in dodaios/ui/web/ |
| Realtime voice | dodaios/realtime/ and its focused tests |
| Providers and plugins | dodaios/plugins/, entry points in pyproject.toml, tests/contract/ |
| Tests and fixtures | tests/, especially tests/fakes/ |
Read the architecture overview for the system map and architecture decisions for past choices. New capabilities must work across supported operating systems and must not depend on one model provider or one developer's machine.
Development setup
Use Python 3.11+ and Git. From your fork or a local checkout:
python -m venv .venv
# macOS/Linux: source .venv/bin/activate
# Windows PowerShell: .\.venv\Scripts\Activate.ps1
python -m pip install -e . --no-deps
python -m pip install -r requirements.txt
python -m pip install -e ".[dev]"
python -c "import dodaios; print(dodaios.__file__)"
The import path must point into this checkout. Re-run
python -m pip install -e . --no-deps after changing plugin entry points.
For an isolated desktop test, use run-dev.bat on Windows or ./run-dev.sh
on macOS/Linux. Both launch a development instance with its own data and ports.
--headless runs the API without a desktop shell. The desktop and voice paths
need the relevant OS permissions and hardware; you can work on tests and docs
without them.
For frontend work, run npm install in dodaios/ui/web/frontend/, then
npm run test and npm run build there. The desktop loads built frontend
files and reloads them automatically; do not commit generated
dodaios/ui/web/dist/ files.
Test and review the change
Keep a PR to one logical change. Describe the user-visible behavior, why it changes, and how you verified it. Include the OS and provider when they matter. Use the PR template for the evidence that matches your change:
| Change | Verification to include |
|---|---|
| Docs or one local view | Check rendered links and media, or show the view in light and dark mode. |
| Existing backend, provider, or OS adapter | Run the focused tests for that family; state which supported cells you exercised and how the others behave. |
| Shared capability or contract | Add contract tests, cover Windows/macOS/Linux behind capability checks, update docs/os-parity.md, and verify a fresh install with one supported key. |
Useful local commands, selected by the change:
pytest tests/path/to/relevant_test.py
pytest tests/contract/
pytest tests/
ruff check dodaios/
ruff format --check dodaios/
mypy dodaios/
Tests use tests/fakes/ rather than unittest.mock. Some repository-wide
checks may have existing failures; report the exact command and failure instead
of claiming a full pass from focused tests. For code that runs at startup, also
run python scripts/ci/check_boot_budget.py.
AI-assisted contributions are welcome when the author can explain the diff, verify its behavior, and respond to review. Write committed code, comments, documentation, logs, and commit messages in English. Keep secrets and personal data out of the repository and PR. Contributions are licensed under Apache 2.0; see licensing details.
For private security reports, follow SECURITY.md. Usage questions belong in Discord or Discussions.