Skip to content

Contributing

Jump to bottom
yohn1985 edited this page Jun 15, 2026 · 1 revision

Contributing

This is open source because the vision is bigger than one person. If you see it, help build it.

Ground rules

  • The jarvis/ package is the source of truth — edit files directly.
  • No infra-specific anything in the core — no hardcoded hosts, paths, brands, or secrets. The core must run on any Linux box.
  • No silent fallbacks. A degraded dependency should be surfaced, not masked as success (this is the project's central reliability principle — see verify.py failing closed).
  • Prefer surgical changes; keep the kernel bounded and the adapters degrade-safe.

Dev setup

git clone https://github.com/yohn1985/jarvisbot.git
cd jarvisbot
./install.sh up
./install.sh selfcheck      # the fitness gate — must stay green

No build step; the core is stdlib-only. Redis/Postgres are optional (everything degrades to in-process / JSONL).

The fitness gate

jarvis/safety/fitness.py is the tamper-proof self-check the self-modification seatbelt relies on. It must pass before any change ships:

python3 jarvis/safety/fitness.py   # prints {"score": N, "max": N, ...}

If you change core behavior, add a check that asserts the invariant you care about (e.g. "verify fails closed", "memory round-trips"). The gate is also where regressions get caught — treat a red check as a blocker.

Where things live

  • jarvis/kernel.py, loop.py, perceive.py — the tick.
  • jarvis/adapters/llm.py — the model router (add a backend here).
  • jarvis/memory/ — working + episodic memory.
  • jarvis/verify.py, jarvis/safety/ — skepticism + the self-mod seatbelt.
  • jarvis/dashboard/ — the stdlib web UI (server.py + dashboard.html); /api/* JSON is stable.
  • skills/ — capabilities (see Skills for how to add one).

Good first contributions

  • A new adapter (a model backend, a notifier, a worksource).
  • A new skill (self-contained, with a SKILL.md).
  • Tests around core invariants (the project is young here — high value).
  • Docs/wiki improvements, and triaging issues.

PRs

Small, focused PRs with a clear description of what changed and why. Make sure selfcheck is green and you didn't introduce a silent fallback or an infra/secret leak. Be kind in review — we're building something ambitious together.

Clone this wiki locally