Contributing

MIRA is open-source under the MIT licence. This page is your Day Zero guide — it covers everything from cloning the repo to getting a pull request merged, including how branches, commits, releases, and CI all fit together. Read this once, end to end, before writing any code.

1. Prerequisites

Before anything else, make sure you have the following installed:

Tool	Required version	How to install
Git	any	git-scm.com
Node.js	22 LTS	nodejs.org or `nvm install 22`
npm	≥ 10	Bundled with Node.js 22
Python	3.11	python.org or `brew install python@3.11`

Node.js 22 LTS is required. If you use nvm, run nvm install 22 && nvm use 22 before anything else.

2. Fork and clone

You work on your own fork — you never push directly to satyendra2013/mira-app.

Fork on GitHub

Go to github.com/satyendra2013/mira-app and click Fork → Create fork.

Clone your fork

git clone https://github.com/<your-username>/mira-app.git
cd mira-app

Add the upstream remote

git remote add upstream https://github.com/satyendra2013/mira-app.git
git fetch upstream

You now have two remotes: origin (your fork) and upstream (the canonical repo). You pull from upstream, push to origin.

3. Set up the dev environment

# Install all Node.js dependencies (also activates husky git hooks automatically)
npm install

# Create a Python virtual environment for the engines
python3.11 -m venv .venv
source .venv/bin/activate        # macOS / Linux
# .venv\Scripts\activate          # Windows

# Install Python dependencies
pip install -r resources/requirements.txt

That’s it. The npm install step also runs husky which installs the git hooks — including the commit message linter. You don’t need to set anything up manually. Verify your environment:

npm run typecheck   # should exit 0
npm run lint        # should exit 0
npm test            # runs the Jest suite

4. Branch naming

Every piece of work lives on its own branch. Branch from main and use the following prefixes so the purpose is immediately clear:

Prefix	Use for
`feat/`	A new feature
`fix/`	A bug fix
`docs/`	Documentation only
`perf/`	Performance improvement
`refactor/`	Internal refactor with no behaviour change
`chore/`	Tooling, dependency updates, CI
`test/`	Adding or fixing tests only

# Always start from an up-to-date main
git checkout main
git pull upstream main

# Create your branch
git checkout -b feat/repl-colour-theme
# or
git checkout -b fix/nae-token-overflow

Keep branch names lowercase, hyphen-separated, and specific. fix/crash is bad. fix/nae-crash-on-empty-document is good.

5. Conventional Commits — the only commit format accepted

MIRA uses Conventional Commits. Every commit message is validated by a git hook the moment you run git commit. A badly formatted commit is rejected immediately — you fix it before it’s recorded.

Format

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

[optional body — explain WHY, not what]

[optional footer — e.g. Closes #123]

The short description must:

be lowercase
not end with a period
be 72 characters or fewer

Types

Type	When to use	Appears in changelog	Version bump
`feat`	Adding new functionality	✨ Features	MINOR
`fix`	Fixing a bug	🐛 Bug Fixes	PATCH
`perf`	Measurable performance improvement	⚡ Performance	PATCH
`docs`	Documentation only	📚 Documentation	none
`refactor`	Code change with no behaviour change	(skipped)	none
`test`	Adding or fixing tests	(skipped)	none
`chore`	Build tooling, CI, dependencies	(skipped)	none
`ci`	CI workflow changes	(skipped)	none

For a breaking change (one that changes the IPC contract, DB schema, or engine API), append ! to the type or add a BREAKING CHANGE: footer:

git commit -m "feat!: redesign IPC session contract"
# or
git commit -m "feat(ipc): new session payload shape

BREAKING CHANGE: session objects now include engineMode field.
Existing integrations must be updated."

Scope (optional but encouraged)

The scope narrows what was changed. Use the name of the module, component, or area:

feat(repl): add colour-coded stderr stream
fix(nae): handle token budget overflow gracefully
docs(skills): clarify custom skill temperature field
chore(deps): upgrade electron to 28.4.0
test(rlm): add multi-hop reasoning test case

Real examples

# Accepted ✅
git commit -m "fix(repl): prevent scroll-lock when console is cleared"
git commit -m "feat(workflows): add human_review step confirmation modal"
git commit -m "docs(mcp): add SSE server setup example"
git commit -m "chore(deps): bump better-sqlite3 to 11.11.0"

# Rejected ❌
git commit -m "Fixed stuff"               # no type
git commit -m "feat: Fix the bug."        # wrong case + period
git commit -m "WIP"                       # no type

6. Development workflow

# Start the app in development mode (hot reload for renderer)
npm run dev

The window opens automatically. Changes to the React renderer hot-reload instantly. Changes to the main process require quitting and re-running npm run dev.

Useful commands

npm run typecheck        # TypeScript type check (no emit)
npm run lint             # ESLint
npm run lint:fix         # ESLint with auto-fix
npm test                 # Jest test suite
npm run test:watch       # Jest in watch mode
npm run test:coverage    # Jest with coverage report

See Build & Run (Development) for debugging the main process and Python engines.

7. Before opening a PR

Run this sequence and make sure everything passes:

npm run typecheck
npm run lint
npm test

If you changed anything user-facing (UI, settings, engine behaviour), update the relevant .mdx file in docs/. Documentation PRs are reviewed as carefully as code PRs.

8. Opening a pull request

Push your branch to your fork

git push origin feat/repl-colour-theme

Open the PR on GitHub

Go to github.com/satyendra2013/mira-app. GitHub will show a banner — click Compare & pull request.Target branch: main. Base repo: satyendra2013/mira-app. Never target a release or hotfix branch unless specifically asked.

Fill out the PR template

The template will be pre-filled. Complete every section:

Summary — one line describing what this PR does
Type of change — tick the relevant box
What changed and why — explain the reasoning, link to the issue if one exists
Testing — which platforms did you verify on?
Checklist — all boxes must be checked before requesting review

CI runs automatically

Three checks run on every PR:

Lint · Typecheck · Test — must be green
Commit message format — validates every commit in the PR against the conventional commits standard

If any check fails, fix it before requesting review.

Respond to review comments

Push new commits to the same branch — the PR updates automatically. Don’t force-push unless the reviewer specifically asks you to squash. Reply to each review comment individually so the reviewer knows what was addressed.

Merge

The maintainer squash-merges approved PRs. Your entire branch becomes one clean commit on main. Delete your branch after merge.

9. Keeping your fork in sync

Before starting any new piece of work, sync your fork with upstream:

git checkout main
git fetch upstream
git merge upstream/main
git push origin main

If you have an in-progress branch that needs upstream changes:

git checkout feat/my-feature
git fetch upstream
git rebase upstream/main
# resolve any conflicts, then:
git push origin feat/my-feature --force-with-lease

Use --force-with-lease (not --force) — it’s a safety check that prevents overwriting someone else’s push.

10. Releases (maintainer only)

Releases are cut by the maintainer from the main branch using release-it. Contributors do not cut releases — this section is here so you understand what happens after your PR merges. See Release Process for the full reference. The short version:

# Cut the next beta
npm run release:beta      # e.g. 0.1.0-beta.1 → 0.1.0-beta.2

# Cut a release candidate
npm run release:rc        # e.g. 1.0.0-rc.1

# Cut a stable release
npm run release           # e.g. 1.0.0

release-it bumps the version in package.json, prepends a CHANGELOG.md entry from your commit history, creates a git tag, and opens a GitHub Release — all in one command.

11. Hotfix branches

A hotfix is an urgent fix applied directly to a released version, not via the normal main flow.

# Branch from the tag you need to fix
git checkout -b fix/crash-on-empty-doc v0.1.0-beta.1

# Apply your fix with a conventional commit
git commit -m "fix(parser): handle empty document upload gracefully"

# Merge back to main
git checkout main
git merge fix/crash-on-empty-doc

# The maintainer then cuts a patch release
npm run release

Quick reference card

Clone            git clone + git remote add upstream
Branch           git checkout -b fix/description
Commit format    fix(scope): short description
Sync fork        git fetch upstream && git merge upstream/main
Push PR          git push origin your-branch → open PR on GitHub
CI checks        lint + typecheck + test + commitlint
Merge style      squash merge by maintainer
Release          npm run release:beta / release:rc / release

Build & Run

Set up your local dev environment

Release Process

How versions are cut and published

Architecture

How Electron, React, and the Python engines fit together

Code of Conduct

Community standards

Edit this page — Open a pull request

Get Started

Core Concepts

Features

Eval Framework

Configuration

Developer Guide

Community

Reference

Contributing

1. Prerequisites

2. Fork and clone

3. Set up the dev environment

4. Branch naming

5. Conventional Commits — the only commit format accepted

Format

Types

Scope (optional but encouraged)

Real examples

6. Development workflow

Useful commands

7. Before opening a PR

8. Opening a pull request

9. Keeping your fork in sync

10. Releases (maintainer only)

11. Hotfix branches

Quick reference card

Build & Run

Release Process

Architecture

Code of Conduct

Get Started

Core Concepts

Features

Eval Framework

Configuration

Developer Guide

Community

Reference

​1. Prerequisites

​2. Fork and clone

​3. Set up the dev environment

​4. Branch naming

​5. Conventional Commits — the only commit format accepted

​Format

​Types

​Scope (optional but encouraged)

​Real examples

​6. Development workflow

​Useful commands

​7. Before opening a PR

​8. Opening a pull request

​9. Keeping your fork in sync

​10. Releases (maintainer only)

​11. Hotfix branches

​Quick reference card

Build & Run

Release Process

Architecture

Code of Conduct

1. Prerequisites

2. Fork and clone

3. Set up the dev environment

4. Branch naming

5. Conventional Commits — the only commit format accepted

Format

Types

Scope (optional but encouraged)

Real examples

6. Development workflow

Useful commands

7. Before opening a PR

8. Opening a pull request

9. Keeping your fork in sync

10. Releases (maintainer only)

11. Hotfix branches

Quick reference card