Contributing — L.U.N.A. Docs

Fork and set up

All contributions go through GitHub pull requests against the main branch.

Click Fork on github.com/Sehastrajit/Luna. This creates your own copy where you can push changes freely.

terminal

git clone https://github.com/<your-username>/Luna.git
cd Luna
git remote add upstream https://github.com/Sehastrajit/Luna.git

terminal

npm install
cd frontend && npm install && cd ..
pip install -r backend/requirements.txt

terminal

copy .env.example .env

Set at minimum user_name, ollama_model, and embedding_model. See the Environment page for details.

terminal

npm run luna -- doctor
npm run luna -- dev

Use a consistent prefix so PRs are easy to filter:

Prefix	Use for	Example
`feature/`	New capabilities	`feature/spotify-queue-control`
`fix/`	Bug fixes	`fix/voice-runtime-crash-on-resume`
`docs/`	Documentation only	`docs/memory-api-reference`
`refactor/`	Internal restructuring, no behaviour change	`refactor/split-tool-registry`
`chore/`	Dependency bumps, config changes	`chore/upgrade-electron-32`

terminal

# Always branch from an up-to-date main
git fetch upstream
git checkout -b feature/my-feature upstream/main

Routers in backend/routers/ must be thin — validate the request, call a service, return the result. No business logic in routers.
All business logic goes in backend/services/. Service functions should be importable and testable in isolation.
Background jobs belong in backend/processes/ and must register themselves in registry.py.
Use type hints on all function signatures.
Never use print() for logging — use the Python logging module.
Avoid non-ASCII characters in log messages — causes UnicodeEncodeError on Windows cp1252.

Components live in frontend/src/components/<Feature>/ — group by domain, not by type.
All backend communication goes through typed wrappers in frontend/src/api/. No raw fetch calls in components.
Global state mutations go in frontend/src/store/index.ts via Zustand actions.
New reusable hooks go in frontend/src/hooks/.
Use TypeScript strictly — no any unless unavoidable, and document why.

All native/Node.js APIs must go through the contextBridge in preload.js. Never expose raw Node APIs to the renderer.
Backend lifecycle management (start, restart, health check) lives in electron/main.js only.

⚠️

Read before large changes

Read docs/ARCHITECTURE.md before making broad architectural changes. Read docs/PROCESSES.md before changing background job behaviour.

Rule	Why
Business logic in services, not routers	Routers are tested at the HTTP boundary. Services are testable in isolation and reusable across routes.
One layer per PR where possible	Mixing backend + frontend + Electron changes makes review hard and widens blast radius.
New tools require permission registration	Every new tool must have a default permission mode in `tool_registry.py` — defaulting to `confirm` is safest.
Agent-created files only in data/workspace/	Prevents Luna from accidentally modifying source files or user documents outside the sandbox.
No hardcoded model names in services	Models are user-configurable via `.env`. Services must read from `config.py`.

Here is the full flow from your branch to merged:

terminal

npm run luna -- check          # backend syntax
cd frontend && npm run build   # TypeScript compile

Both must pass cleanly before opening a PR.

terminal

git push origin feature/my-feature

Open a PR on GitHub against main. Fill in:

Push new commits to your branch — don't force-push during review as it makes it harder to see what changed. Squash on merge is enabled.

Once approved, the PR will be squash-merged into main. Your branch is deleted automatically.

Run through this before requesting review:

Never commit .env, data/, *.db, chroma/, or log files.
Do not submit conversation logs, memory exports, or personal data of any kind.
API keys, tokens, and secrets are never acceptable in source code — use .env and config.py.
If your contribution involves external service calls, document which data is sent and ensure users can opt out via configuration.