Contributing

Thanks for your interest in contributing! We favor small, focused PRs and clear intent over big bangs. This guide explains how to get set up, the workflow we use, and a few project‑specific conventions.

Quick Start

Prerequisites

• Node.js 20.0.0+ (recommended: 22.20.0) and Git
• Optional (recommended for end‑to‑end testing):
  • GitHub CLI (brew install gh; then gh auth login)
  • At least one supported coding agent CLI (see Providers)

Setup

# Fork this repo, then clone your fork
git clone https://github.com/<you>/emdash.git
cd emdash

# Use the correct Node.js version (if using nvm)
nvm use

# Quick start: install dependencies and run dev server
npm run d

# Or run separately:
npm install
npm run dev

# Type checking, lint, build
npm run type-check
npm run lint
npm run build

Tip: During development, the renderer hot‑reloads. Changes to the Electron main process (files in src/main) require a restart of the dev app.

Project Overview

• src/main/ – Electron main process, IPC handlers, services (Git, worktrees, PTY manager, DB, etc.)
• src/renderer/ – React UI (Vite), hooks, components
• Local database – SQLite file created under the OS userData folder (see "Local DB" below)
• Worktrees – Git worktrees are created outside your repo root in a sibling worktrees/ folder
• Logs – Agent terminal output and app logs are written to the OS userData folder (not inside repos)

Development Workflow

1. Create a feature branch

git checkout -b feat/<short-slug>

2. Make changes and keep PRs small and focused

• Prefer a series of small PRs over one large one.
• Include UI screenshots/GIFs when modifying the interface.
• Update docs (README or inline help) when behavior changes.

3. Run checks locally

npm run format      # Format code with Prettier (required)
npm run type-check  # TypeScript type checking
npm run lint        # ESLint
npm run build       # Build both main and renderer

4. Commit using Conventional Commits

• feat: – new user‑facing capability
• fix: – bug fix
• chore:, refactor:, docs:, perf:, test: etc.

Examples:

fix(opencode): change initialPromptFlag from -p to --prompt for TUI

feat(docs): add changelog tab with GitHub releases integration

5. Open a Pull Request

• Describe the change, rationale, and testing steps.
• Link related Issues.
• Keep the PR title in Conventional Commit format if possible.

Code Style and Patterns

TypeScript + ESLint + Prettier

• Run npm run format before committing to ensure consistent formatting.
• Keep code type‑safe. Run npm run type-check before pushing.
• Run npm run lint and address warnings where reasonable.

Electron main (Node side)

• Prefer execFile over exec to avoid shell quoting issues.
• Never write logs into Git worktrees. All logs belong in the Electron userData folder.
• Be conservative with console logging; noisy logs reduce signal. Use clear prefixes.

Git and worktrees

• The app creates worktrees in a sibling ../worktrees/ folder.
• Do not delete worktree folders from Finder/Explorer; if you need cleanup, use:
  • git worktree prune (from the main repo)
  • or the in‑app workspace removal

Documentation

When writing or updating docs, keep the tone clear and conversational. Use complete sentences and natural language rather than long bullet point lists. Avoid em dashes (—); use commas, periods, or rephrase instead.

Renderer (React)

• Components live under src/renderer/components; hooks under src/renderer/hooks.
• Agent CLIs are embedded via terminal emulation (xterm.js) - each agent runs in its own PTY.
• Use existing UI primitives and Tailwind utility classes for consistency.
• Aim for accessible elements (labels, aria-* where appropriate).

Local DB (SQLite)

Location (Electron app.getPath('userData')):

• macOS: ~/Library/Application Support/emdash/emdash.db
• Linux: ~/.config/emdash/emdash.db
• Windows: %APPDATA%\emdash\emdash.db

Reset: quit the app, delete the file, relaunch (the schema is recreated).

Issue Reports and Feature Requests

Use GitHub Issues. Include:

• OS, Node version
• Steps to reproduce
• Relevant logs (renderer console, terminal output)
• Screenshots/GIFs for UI issues

Release Process (maintainers)

Use npm's built-in versioning to ensure consistency:

# For bug fixes (0.2.9 → 0.2.10)
npm version patch

# For new features (0.2.9 → 0.3.0)
npm version minor

# For breaking changes (0.2.9 → 1.0.0)
npm version major

This automatically:

1. Updates package.json and package-lock.json
2. Creates a git commit with the version number (e.g., "0.2.10")
3. Creates a git tag (e.g., v0.2.10)

Then push to trigger the CI/CD pipeline.

What happens next

Two GitHub Actions workflows trigger on version tags:

macOS Release (.github/workflows/release.yml):

1. Builds the TypeScript and Vite bundles
2. Signs the app with Apple Developer ID
3. Notarizes via Apple's notary service
4. Creates a GitHub Release with DMG artifacts for arm64 and x64

Linux/Nix Build (.github/workflows/nix-build.yml):

1. Computes the correct npmDepsHash from package-lock.json
2. Builds the x86_64-linux package via Nix flake
3. Pushes build artifacts to Cachix