Contributing

Monorepo structure. Conventional commits. Local-first ethos.

loci is open source. Contributions welcome.

---

Repository structure

Loci/
├── packages/
│   ├── extension/          # Chrome MV3 extension (Vite + TypeScript)
│   ├── desktop/            # Tauri v2 desktop app (Rust + WebView)
│   └── server/             # MCP server (Rust)
├── docs/                   # VitePress documentation (you are here)
├── landing/                # loci.garden landing page
└── package.json            # Root workspace config

Each package has its own package.json (for JS) or Cargo.toml (for Rust).

---

Development setup

Extension

cd packages/extension
npm install
npm run dev          # Watch mode with hot reload

Load the extension in Chrome:

1. chrome://extensions > Enable Developer Mode
2. Load unpacked > select packages/extension/dist/

The extension reloads automatically on file changes.

Desktop app

cd packages/desktop
npm install
npm run tauri dev    # Runs Tauri in dev mode

Requires Rust toolchain. See Tauri prerequisites.

MCP server

cd packages/server
cargo run            # Runs on localhost:3721

Docs

cd docs
npm install
npm run dev          # VitePress dev server

---

Adding a new platform

To add support for a new AI chat platform (e.g., Gemini):

1. Add selectors to packages/extension/src/platforms/platforms.config.ts:

export const platforms = {
  // ...existing
  gemini: {
    hostPatterns: ["gemini.google.com"],
    containerSelector: "[data-message-id]",
    userSelector: "[data-author='user']",
    assistantSelector: "[data-author='model']",
  },
};

2. Create content script at packages/extension/src/content/gemini.ts:

import { attachObserver } from "./observer";
import { platforms } from "../platforms/platforms.config";

attachObserver(platforms.gemini);

3. Register in manifest at packages/extension/manifest.json:

{
  "content_scripts": [
    {
      "matches": ["*://gemini.google.com/*"],
      "js": ["src/content/gemini.ts"]
    }
  ]
}

4. Test on the live site. Verify MutationObserver captures turns correctly.

5. Update docs: add the platform to the supported platforms table in /docs/extension/index.md.

---

Commit format

Use Conventional Commits:

<type>(<scope>): <description>

[optional body]

Types:

Type	Use for
feat	New feature
fix	Bug fix
docs	Documentation only
refactor	Code change that neither fixes a bug nor adds a feature
test	Adding or updating tests
chore	Build process, dependencies, tooling

Scopes:

Scope	Package
extension	Browser extension
desktop	Tauri app
server	MCP server
docs	Documentation
landing	Landing page

Examples:

feat(extension): add Gemini platform support
fix(server): handle empty room context gracefully
docs: add MCP API reference
chore(extension): upgrade MiniSearch to 7.1.0

---

Pull requests

1. Fork the repo
2. Create a feature branch (git checkout -b feat/gemini-support)
3. Make your changes
4. Run tests (npm test in relevant package)
5. Commit with conventional commit format
6. Push and open a PR against main

PRs require one approval before merge.

---

Issue labels

Label	Meaning
bug	Something is broken
feature	New functionality request
docs	Documentation improvement
good-first-issue	Suitable for new contributors
platform	New platform support request
security	Security-related (handled privately)

---

Code style

• TypeScript: Strict mode, no any unless unavoidable
• Rust: cargo fmt and cargo clippy clean
• Naming: camelCase for JS, snake_case for Rust

No linter wars. Match the existing code.

---

Questions

Open a GitHub Discussion or reach out at hux@nymtech.net.