How to Change

How to Change

Practical recipes for common contributor tasks. Always keep Gotchas in mind.

Change the IPC / window.api surface

1. Edit app/src/types/api.d.ts (AnyLmApi).
2. Implement in app/preload.ts (ipcRenderer.invoke / on / send).
3. Handle in app/src/main/ipc.ts (ipcMain.handle / on).
4. Call from renderer modules.
5. bun run typecheck — ambient types make renames fail the build on purpose.

Streaming and confirms use events, not invoke-only patterns. Mirror existing chat:* / tool-confirm channels when adding async push APIs.

Change chat behavior

Intent	Where
System prompt assembly	ipc.ts (orchestration) + context.ts / memory.ts / skills instructionsBlock
Governance / PII / limits	governance.ts, policy-engine.ts, api/*
Tool loop / round limits	ipc.ts (15), agents/workers.ts (3)
Multi-agent routing	agents/* + flags in settings; project-coding forces single-agent
Streaming UI	renderer/js/chat.ts + activity/working strip modules
Persist messages	store.ts / chats.ts

Read Chat Pipeline before large edits.

Add a setting

1. Extend settings type in domain.d.ts.
2. Default in settings.ts (file: llmeter-settings.json).
3. Expose get/set via IPC if renderer needs it (update api.d.ts + preload + ipc).
4. Wire UI in settings views.
5. Consume in main where the behavior lives.

Add a governance / org API route

1. Add handler module under app/src/main/api/.
2. Register path in api/index.ts dispatch table (keep REST shapes).
3. Update firebase/firestore.rules — required for authz.
4. Update indexes if queries need them.
5. Call via auth.request from main or expose through IPC for UI.

Remember: usage limits are cooperative on Spark (clients must report).

Add UI chrome / a view

1. Prefer existing patterns in renderer/js/ (*-view.ts, rail/, sidebar/).
2. Styles in styles.css (site-theme / glass language).
3. State in state.ts; pure bits in views.ts when possible.
4. No Node in renderer — only window.api.

Touch RAG / embeddings

• Chunking / retrieve: rag.ts, context.ts
• Chroma lifecycle: chroma-server.ts, chroma.ts, startup-deps.ts
• Embed model: embed.ts + ANYLM_EMBED_MODEL
• Soft-fail: never assume Chroma is up

Change Ollama integration

• Client: ollama.ts
• First-run: ollama-setup/, renderer setup-wizard.ts
• Host override: env ANYLM_OLLAMA_HOST / OLLAMA_HOST
• Model catalog UI: model-catalog.ts + renderer models browser

Change packaging / release

• Version: app/package.json must match git tag vX.Y.Z
• Workflow: .github/workflows/release.yml → build.yml
• Notes: add docs/releases/vX.Y.Z.md when tagging
• See Build & Release

Change Firebase sign-in page

• firebase/hosting/public/
• Deploy with firebase deploy
• App opens system browser with ?provider=&port=

Refactor safely

1. Prefer graph / tests for blast radius (bun test, typecheck).
2. Keep ambient types as the contract — don’t duplicate interfaces in renderer.
3. Don’t revive auth-backend/ as a runtime dependency.
4. Don’t put secrets in app/.env — build will refuse many patterns.

Checklist before opening a PR

• cd app && bun run typecheck
• bun test
• Manual smoke for the path you touched (chat / tools / auth / settings)
• Rules updated if Firestore shape changed
• IPC triple updated if API changed
• No secrets in diffs