Contributing code

Contribute to Linkr's code the way the main contributor does, with VS Code and Claude Code: install from source, create a branch, let each task run in its own worktree, and use the code-review, dependabot-triage and update-website-docs skills.

In short

The main contributor develops Linkr with VS Code and Claude Code, on the Opus models, and the repository is set up for that — but it is one way of working, not a requirement. You install Linkr from source, work on your own branch, and every task you hand to Claude runs in its own worktree — so several agents can move forward in parallel without getting in each other’s way. Three skills in the repository cover code review, security alerts and the documentation.

You don't need to write code to help

Reporting a bug, saying a screen is confusing, describing a use case Linkr handles poorly: all of this goes through an issue, on FramaGit or on the GitHub mirror. The repository’s CONTRIBUTING.md file describes these contributions. This page is for those who want to change the code.

The tools

The main contributor works in VS Code, with the Claude Code extension and Anthropic’s Opus models, picked with the /model command. This is the setup the repository is prepared for today: its instructions and skills are written for Claude Code.

It is not a requirement: you can use the editor, assistant and model of your choice. What Claude Code adds is the context: when it opens the repository, it reads the CLAUDE.md file, which points to the code conventions (docs/conventions.md), the interface components to reuse (docs/ui-patterns.md) and the architecture (docs/architecture.md). It applies those rules without you having to repeat them.

This tooling is expected to change. In particular, an AGENTS.md file — the open format most coding assistants read — is planned, so that these instructions work for any agent and the repository depends less on Claude Code.

Installing Linkr from source

To develop, Linkr is installed in server mode, from source: you clone the repository, install the Node.js and Python dependencies, and a single command starts the backend and the frontend with hot reload. The full step-by-step procedure is in Manual install.

git clone https://framagit.org/interhop/linkr/linkr.git
cd linkr
npm install

If you also plan to work on the documentation, clone the website repository next to Linkr’s, in the same parent folder:

git clone https://framagit.org/interhop/linkr/linkr-website.git

Working on a branch

Create your branch

Start from the development branch and create your own, named after what you are doing:

git checkout -b feature/export-csv

Hand the tasks to Claude

Open the repository in VS Code, start Claude Code and describe what you want. For every new task, Claude creates a worktree: a working copy of the repository, in a sibling folder, with its own sub-branch, its own ports and its own data folder. The worktree starts from your branch as committed: anything uncommitted does not come along.

# folder ../linkr-export-csv-dialog, branch feature/export-csv-dialog
npm run worktree:new -- export-csv-dialog

Run and review

Claude never starts the app itself: it gives you the command to paste in a new VS Code terminal, the frontend address, and how to add the worktree to your window (File › Add Folder to Workspace…) to see its files and changes.

Merge

Once the task is done and reviewed, you merge its branch into yours, from your main folder, then remove the worktree:

git merge feature/export-csv-dialog
npm run worktree:remove -- export-csv-dialog --branch

Several agents at once

That is the whole point of worktrees: each agent has its own files, its own git status and its own running app, without seeing the others’ work in progress. You can start three tasks in three Claude Code conversations, and merge them into your branch as each one lands. The details are in docs/worktrees.md.

When your branch is ready, push it and open a merge request on FramaGit. On git push, hooks run the quality checks — lint, type checking, tests — and block the push if one of them fails.

The skills

A skill is a set of instructions stored in the repository (.claude/skills/), which Claude Code loads when you type its name after a slash. The repository holds several; three are used day to day.

/code-review

A structured review of the latest changes: security, code quality, consistency with the rest of the app, useless comments, conventions. Claude picks up where the previous review stopped — each pass is logged, with its date and the last reviewed commit, in REVIEW-LOG.md. Run it before pushing a series of changes, or before a release.

/dependabot-triage

Triage of the GitHub mirror’s Dependabot security alerts. Claude classifies each alert — already fixed once the branch is merged, false positive, blocked upstream, or to be fixed — then proposes the fix or the dismissal, and records each decision in TRIAGE-LOG.csv so the same alert is never processed twice. It needs access to the GitHub repository and a gh auth login session: this skill is mostly for maintainers.

/update-website-docs

Updating this documentation, when a feature changes or a page is missing. Claude reads the app’s code to reuse the exact interface labels, writes the page in French and in English, updates the navigation, and checks the links and the site build. It expects linkr-website to be cloned next to linkr.

Never any patient data

Not in an issue, a screenshot, a sample file, or a conversation with an assistant — not even partially de-identified. Work with the demo data.

Going further

Manual install — install Linkr from source.
Deployment modes — what changes between the browser alone and the server.
Skills — user-side skills, to drive Linkr from an agent.