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.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
docs: make GitHub landing page welcoming to maintainers
Ruben Lütkecf9234fe2a39
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.ymlindex a3174c8b42..ba03868cad 100644--- a/.github/ISSUE_TEMPLATE/config.yml+++ b/.github/ISSUE_TEMPLATE/config.yml@@ -2,7 +2,7 @@ blank_issues_enabled: truecontact_links:- name: Questions & community (Discord)url: https://discord.gg/x7USduHxbc- about: Usage questions, setup help, and general chat. Fastest answer, usually same day.+ about: Usage questions, setup help, and general chat.- name: Ideas & design discussionurl: https://github.com/PersonalJarvis/PersonalJarvis/discussionsabout: Propose a feature, ask how something is meant to work, or float an approach before you build it.diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.mdindex f340dd69dc..24bda3dae5 100644--- a/.github/PULL_REQUEST_TEMPLATE.md+++ b/.github/PULL_REQUEST_TEMPLATE.md@@ -11,7 +11,7 @@ the same evidence as a new speech provider, and we do not pretend otherwise.## Related issue-<!-- "Closes #123", or "none" if there isn't one. Small fixes don't need an issue first. -->+<!-- "Closes #123", or "none" if there isn't one. Small fixes don't need an issue first. For larger changes, link the design discussion. -->---@@ -28,7 +28,8 @@ the same evidence as a new speech provider, and we do not pretend otherwise.<details open><summary><b>Docs, comments, or translations only</b></summary>-- [ ] Nothing else. Open it — this is the whole checklist.+- [ ] Links and media touched by this change resolve in the rendered page.+- [ ] Public text contains no personal data or credentials.</details>diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 79b37bbdaf..3ab43ff4ab 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -1,242 +1,110 @@-<p align="center">- <a href="https://github.com/PersonalJarvis/PersonalJarvis">- <img src="assets/brand/banner.png" alt="Personal Jarvis" width="520" />- </a>-</p>+# Contributing to Personal Jarvis-<h1 align="center">Contributing</h1>+Personal Jarvis 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.-<p align="center">- Thanks for being here. Small PRs, friendly review, same-day help on Discord.<br />- Everything you need to get started fits on this screen.-</p>+## Choose a first contribution-<p align="center">- <a href="https://github.com/PersonalJarvis/PersonalJarvis/pulls"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-FFD60A?style=flat-square&labelColor=0A0A0A" /></a>- <a href="https://github.com/PersonalJarvis/PersonalJarvis/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22"><img alt="Good first issues" src="https://img.shields.io/badge/good%20first%20issues-open-FFD60A?style=flat-square&labelColor=0A0A0A" /></a>- <a href="https://discord.gg/x7USduHxbc"><img alt="Discord" src="https://img.shields.io/badge/Discord-join-FFD60A?style=flat-square&logo=discord&logoColor=0A0A0A&labelColor=0A0A0A" /></a>- <a href="LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/License-Apache_2.0-FFD60A?style=flat-square&labelColor=0A0A0A" /></a>-</p>-------## Your first PR in five steps--1. **Fork and clone**, then install:- ```bash- pip install -e . --no-deps && pip install -r requirements.txt && pip install -e ".[dev]"- ```-2. **Pick something.** A [good first issue](https://github.com/PersonalJarvis/PersonalJarvis/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22), or simply the thing that annoyed you.-3. **Change one thing** and run `pytest -m "not slow"` (UI work: `npm run test` in `jarvis/ui/web/frontend/`).-4. **Open the PR.** The template has one short block per kind of change — tick yours, skip the rest. A typo fix owes nothing else.-5. **Stuck?** Ask on [Discord](https://discord.gg/x7USduHxbc). Someone usually answers the same day.--That's it. You don't need to read the rest of this page to open a PR, and you don't need to-understand the whole system to fix one piece of it.--> [!TIP]-> **A first PR doesn't have to be perfect.** If CI fails on a rule you've never heard of,-> that's normal and not a rejection — say so in the PR and we'll walk you through it.-------## Two things worth knowing--- **We write in English.** Code, comments, docs, commit messages and PR text are English so- that everyone can read them. Talk to us in any language you like — the repo itself stays- English, and CI checks that for you so you don't have to think about it.-- **Keep each PR to one change.** Small PRs get reviewed fast and merged fast.-------## What we'd love help with--| | |+| Starting point | A useful, reviewable result ||---|---|-| **Bug fixes** | Always first. Crashes, wrong behaviour, lost data, anything that made the voice path worse. |-| **Cross-platform work** | Linux, macOS, Windows and headless servers are equal here. Making something work on a platform it didn't before is a great contribution. |-| **Security hardening** | Prompt injection, the line between what the user said and what a tool observed, path traversal. See [`SECURITY.md`](SECURITY.md). |-| **Speed and robustness** | Voice latency, retries, honest degradation, the rule that a conversation never blocks. |-| **New providers and plugins** | Across all seven groups (wake, STT, TTS, brain, harness, tool, channel). Provider-agnostic, passing the contract suite. |-| **Docs** | Any time. Unclear sentence, missing step, outdated screenshot — fix it. |+| [Open bugs](https://github.com/PersonalJarvis/PersonalJarvis/issues?q=is%3Aissue%20is%3Aopen%20label%3Abug) | 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 `jarvis/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](docs/os-parity.md) first. |++Use [GitHub Issues](https://github.com/PersonalJarvis/PersonalJarvis/issues/new/choose)+for a concrete bug or task. For a larger design, use+[Discussions](https://github.com/PersonalJarvis/PersonalJarvis/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; browse open bugs or propose a small task if that list is empty.++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.++## Find your way around++| Area | Start here |+|---|---|+| Core contracts and events | `jarvis/core/protocols.py`, `jarvis/core/events.py` |+| Desktop and web UI | `jarvis/ui/web/frontend/`; backend routes in `jarvis/ui/web/` |+| Realtime voice | `jarvis/realtime/` and its focused tests |+| Providers and plugins | `jarvis/plugins/`, entry points in `pyproject.toml`, `tests/contract/` |+| Tests and fixtures | `tests/`, especially `tests/fakes/` |-> [!TIP]-> Planning something bigger than a fix? Open an issue first so we can agree on the approach.-> It keeps you from writing a PR that was never going to land.+Read the [architecture overview](docs/architecture-overview.md) for the system+map, [architecture decisions](docs/adr/) for past choices, and+[AGENTS.md](AGENTS.md) for the binding engineering rules. In particular, new+capabilities must work across supported operating systems and must not depend+on one model provider or one developer's machine.----+## Development setup-## Dev setup+Use Python 3.11+ and Git. From your fork or a local checkout:```bash-git clone https://github.com/PersonalJarvis/PersonalJarvis ~/personal-jarvis-cd ~/personal-jarvis-python -m venv .venv-source .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1--pip install -e . --no-deps # activates the plugin entry-points-pip install -r requirements.txt # runtime dependencies-pip install -e ".[dev]" # pytest, ruff, mypy--python -m jarvis --wizard # interactive first-run setup-python -m jarvis.ui.web.launcher # run it (add --headless for a server)+# 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 jarvis; print(jarvis.__file__)"```-Frontend: `npm install` in `jarvis/ui/web/frontend/`, then `npm run dev` / `npm run build` /-`npm run test`.--> [!NOTE]-> After editing entry-points in `pyproject.toml`, re-run `pip install -e . --no-deps`. That is-> what activates new plugins, and skipping it is the #1 reason a plugin "does not exist".+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.-### Running the checks--```bash-pytest -m "not slow" # fast subset — enough for most PRs-pytest tests/ # full suite-pytest tests/contract/ -v # for new STT/Brain/Tool/Channel providers+For frontend work, run `npm install` in `jarvis/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+`jarvis/ui/web/dist/` files.-ruff check jarvis/ && ruff format --check jarvis/-mypy jarvis/--cd jarvis/ui/web/frontend && npm run test && npm run build-```+## Test and review the change-Tests use fakes from `tests/fakes/`, not mocks.+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](.github/PULL_REQUEST_TEMPLATE.md) for the evidence that+matches your change:------## Before you open the PR--The PR template scales with what you touched. Find your row, ignore the rest:--| Your change | What it owes |+| Change | Verification to include ||---|---|-| Docs, comments, translations | Nothing beyond English |-| Web UI | `npm run test` + `npm run build`, works in light **and** dark mode, a screenshot. Don't commit `jarvis/ui/web/dist/` — the maintainer rebuilds the bundle |-| Bug fix, ordinary Python | `pytest -m "not slow"` green, a test for the fixed behaviour, `ruff` clean |-| New provider | The above plus `pytest tests/contract/`, no `import jarvis.*` in the module, honest degradation without a key |-| A shared contract (capability, config schema, turn-taking, credentials, OS backend) | The above plus: which platforms you touched and what the others do now, a boot on headless `python:3.11-slim`, `CHANGELOG.md` |--Unsure which row you're in? Open the PR and ask. We'd rather tell you in review than have-you guess high and waste an evening.--Describe what changed and why, link the issue it closes. By contributing you agree your work-is licensed under the [Apache License 2.0](LICENSE) — see-[`docs/licensing.md`](docs/licensing.md).-----+| 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. See the T3 rules in `AGENTS.md`. |-## Going deeper+Useful local commands, selected by the change:-Reference for when you want it. None of this is required for a first PR.--<details>-<summary><b>The architecture in four rules</b></summary>--<br />--Personal Jarvis is an 8-layer system. Four rules matter before you write anything:--1. **Layers talk through protocols.** Higher layers reach lower ones only through- `jarvis/core/protocols.py`. Anything sideways goes over the EventBus as a typed,- immutable event.-2. **Everything streams.** `Brain`, `STT`, `TTS` and `Harness` methods return an- `AsyncIterator`; a provider that cannot stream yields exactly one element.-3. **No vendor is load-bearing.** Never hardcode one brain provider; `cfg.brain.primary`- decides.-4. **The router dispatches rather than doing.** Heavy work becomes a mission in an isolated- `git worktree`, under a worker-and-critic loop.--For the deep version read [`docs/LLM-CONTEXT.md`](docs/LLM-CONTEXT.md) (a dense-engineering snapshot) and [`CLAUDE.md`](CLAUDE.md) (the binding conventions, including the-cross-platform doctrine in section 2).--</details>--<details>-<summary><b>Plugin, tool, or skill?</b></summary>--<br />--The most common design question. Pick the smallest thing that fits:--| | Plugin | Tool | Skill |-|---|---|---|---|-| What it is | A swappable provider | A brain-callable action inside one turn | An authored, multi-step workflow |-| Where it lives | `jarvis/plugins/<group>/`, one of 7 groups | Registered tool, run via `ToolExecutor` | Authored skill; generated ones start as `draft` |-| The one rule | No `import jarvis.*` in the module; new STT/Brain/Tool/Channel must pass `tests/contract/` | Never call `Tool.execute()` directly | Never auto-activated |--A swappable backend is a plugin. A single action the brain can call is a tool. A multi-step-workflow somebody wrote down is a skill.--**Marketplace plugins** (the connectors in the app's Plugins store — GitHub, Notion, Slack, …)-are a separate, fourth thing. New submissions are packaged per the vendor-neutral-[Agent Plugins standard v1.0.0](https://agent-plugins.org/): a directory with a-`plugin.json`, an `mcp.json` when the service has an MCP server, and everything-Jarvis-specific under the `io.github.personaljarvis` extension namespace. Field mapping and-the migration tracker: [`docs/marketplace/agent-plugins-standard.md`](docs/marketplace/agent-plugins-standard.md).--</details>--<details>-<summary><b>Adding a TTS provider: four registrations, not one</b></summary>--<br />--The entry point in `pyproject.toml` makes a TTS provider discoverable, but the config path-builds providers through `_build_provider()` in-[`jarvis/plugins/tts/__init__.py`](jarvis/plugins/tts/__init__.py) — that is where each-family's own voice, model and sub-table handling lives, and where leftover values from a-previous provider get scrubbed. A provider with an entry point but no branch there hits the-`Unknown TTS provider` fallback: Gemini speaks instead of you, with only a log line to say so.--The four places:--1. The entry point in `pyproject.toml`.-2. A branch in `_build_provider()`.-3. An alias set wired into `_canonical_tts_name()`, so every spelling of your provider- resolves to one family.-4. An entry in `_TTS_SECRET_CANDIDATES` if it needs a key — without it the credential gate- treats the provider as always available.--</details>--<details>-<summary><b>Conventions CI enforces</b></summary>--<br />--You'll find out either way; better to know first:+```bash+pytest tests/path/to/relevant_test.py+pytest tests/contract/+pytest tests/+ruff check jarvis/+ruff format --check jarvis/+mypy jarvis/+```-| Area | The rule |-|---|---|-| Language | English artifacts only (`language-policy` gate) |-| Risk tier | `ToolExecutor.execute()` is the only authorized execution path |-| Router | `ROUTER_TOOLS` is a frozenset; no spawn tool in a worker tool set |-| Enum drift | Strings crossing module boundaries use the five-layer pattern plus a parity test |-| Config writes | Mutate `jarvis.toml` only via `config_writer` (lock, tempfile, BOM-safe) |-| Subprocess | Always pass `NO_WINDOW_CREATIONFLAGS` |-| Secrets | Only via `get_secret()`; never in code, config, or commits |-| Dependencies | No Windows-only or GPU-only dependency in the base install; extras only |--The full anti-pattern register lives in [`docs/LLM-CONTEXT.md`](docs/LLM-CONTEXT.md).--</details>-------## Community--<p align="center">- <a href="https://discord.gg/x7USduHxbc"><img alt="Discord" src="https://img.shields.io/badge/Discord-join_the_server-FFD60A?style=for-the-badge&logo=discord&logoColor=0A0A0A&labelColor=0A0A0A" /></a>- <a href="https://x.com/Ruben_Luetke"><img alt="X" src="https://img.shields.io/badge/X-follow-FFD60A?style=for-the-badge&logo=x&logoColor=0A0A0A&labelColor=0A0A0A" /></a>-</p>--<p align="center">- <a href="https://discord.gg/x7USduHxbc">Discord</a> ·- <a href="https://x.com/Ruben_Luetke">X</a> ·- <a href="https://github.com/PersonalJarvis/PersonalJarvis/issues">Issues</a> ·- <a href="CODE_OF_CONDUCT.md">Code of conduct</a>-</p>+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](LICENSE); see [licensing details](docs/licensing.md).++For private security reports, follow [SECURITY.md](SECURITY.md). For conduct+concerns, see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Usage questions belong+in [Discord](https://discord.gg/x7USduHxbc) or+[Discussions](https://github.com/PersonalJarvis/PersonalJarvis/discussions).diff --git a/README.md b/README.mdindex 4fd7d2f42c..c6bc57292c 100644--- a/README.md+++ b/README.md@@ -46,6 +46,14 @@ and [how the system fits together](#how-it-works).[Discord](https://discord.gg/x7USduHxbc) · [X](https://x.com/Ruben_Luetke) ·[Instagram](https://www.instagram.com/personaljarvis/)+**Build with us.** Personal Jarvis spans a Python/FastAPI backend, a React/TypeScript+desktop interface, voice, agents, and OS integrations. If you want to improve a+specific part and help maintain it over time, start with a scoped issue or PR.+[Choose a contribution](https://github.com/PersonalJarvis/PersonalJarvis/blob/main/CONTRIBUTING.md#choose-a-first-contribution) ·+[Set up a development checkout](https://github.com/PersonalJarvis/PersonalJarvis/blob/main/CONTRIBUTING.md#development-setup) ·+[See the architecture](https://github.com/PersonalJarvis/PersonalJarvis/blob/main/docs/architecture-overview.md) ·+[Discuss an approach](https://github.com/PersonalJarvis/PersonalJarvis/discussions)+## Install**Windows — PowerShell**@@ -420,21 +428,21 @@ Open **Docs** in the app for searchable product guides, or follow the topics her| [Architecture decisions](https://github.com/PersonalJarvis/PersonalJarvis/tree/main/docs/adr/) | Design decisions and their context. || [README media source](https://github.com/PersonalJarvis/PersonalJarvis/blob/main/scripts/readme-video/README.md) | Provenance, example data, still previews, and rendering commands. |-## Community and contributing--Follow the project on the [website](https://personaljarvis.ai),-[X](https://x.com/Ruben_Luetke), and-[Instagram](https://www.instagram.com/personaljarvis/).--Questions, ideas, and bug reports are welcome on [Discord](https://discord.gg/x7USduHxbc)-and [GitHub](https://github.com/PersonalJarvis/PersonalJarvis/issues/new/choose).-Watch walkthroughs on the [Personal Jarvis channel](https://www.youtube.com/@PersonalJarvis).--Read [CONTRIBUTING.md](https://github.com/PersonalJarvis/PersonalJarvis/blob/main/CONTRIBUTING.md) before a pull request. Hardware reports,-provider integrations, accessibility improvements, and native-language feedback-are especially useful. AI-assisted contributions are welcome; review focuses-on the change and its evidence. Repository contributions are written in English.-Report vulnerabilities privately through [SECURITY.md](https://github.com/PersonalJarvis/PersonalJarvis/blob/main/SECURITY.md).+## Build with us++Contributions are useful across desktop accessibility, platform support,+voice reliability, provider integrations, tests, and documentation. The+[contributor guide](https://github.com/PersonalJarvis/PersonalJarvis/blob/main/CONTRIBUTING.md)+maps those areas to code, a development setup, and review expectations. A small,+reproducible improvement is a good place to begin; you do not need to understand+the entire application first.++Use [issues](https://github.com/PersonalJarvis/PersonalJarvis/issues) for bugs+and scoped work, and [Discussions](https://github.com/PersonalJarvis/PersonalJarvis/discussions)+to agree on a larger design or offer sustained help in a subsystem. AI-assisted+contributions are welcome when the author can explain and verify the result.+Repository contributions are written in English. Report vulnerabilities+privately through the [security policy](https://github.com/PersonalJarvis/PersonalJarvis/blob/main/SECURITY.md).## Contributors