Skip to main content
To contribute to Linger, run it from source, make your change, and run the checks. Then open a pull request on GitHub. The repository’s CONTRIBUTING.md is the source for this page. Read the nearest AGENTS.md before you change an app. pnpm dev runs Web, TeamHub, and the node-services process on your machine. Web and TeamHub reload when you save. node-services does not watch files: restart it, or run pnpm --filter @linger/node-services dev for a watching process. pnpm dev starts no containers. You run PostgreSQL yourself. To run Linger for daily use, follow Install with Docker Compose instead. Linger needs no model gateway or API key of its own. Agent model calls, including the background work of agent memory and the personal memory, run on the Codex or Claude Code of the user’s own computer. Grok Live voice mode calls xAI from the server.

​
Check what you need

Install these tools before you start:
  • Node.js 26.5.x and pnpm 11.7.0. The repository pins the Node version in .node-version.
  • Go 1.26.5.
  • PostgreSQL 17 with the pgvector extension, running on your machine.
  • FFmpeg, with ffmpeg and ffprobe on PATH, if you work on voice recording.
  • Docker with Docker Compose, only for the Compose setup and the TeamHub integration tests.

​
Run Linger from source

1

Clone the repository

2

Install the dependencies

3

Create your environment file

Set TEAMHUB_DATABASE_URL in .env to your database. The default matches the postgres service of the root docker-compose.yml. Only the optional personal keys for Composio and Soniox are empty.
4

Start the database if you use the Compose one

Skip this step if you run PostgreSQL yourself.
5

Start Linger

The command migrates the database that TEAMHUB_DATABASE_URL names. Then it runs Web, TeamHub, and node-services.
6

Check every service

In a second terminal, run:
Then open http://localhost:3000.
pnpm dev prepares a local owner account. OWNER_EMAIL in .env sets its email, and the default is owner@linger.local. pnpm dev:check calls the health endpoint of each service: For voice, set SONIOX_API_KEY or XAI_API_KEY in .env and put livekit-server on your PATH (brew install livekit on macOS, curl -sSL https://get.livekit.io | bash on Linux). pnpm dev then runs it on the ports and keys LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET name, and node-services starts the voice workers. Point LIVEKIT_URL at another host to use a LiveKit server you run elsewhere. To run everything in containers, voice included, follow Install with Docker Compose. To build and test the desktop app, which also carries the installer, see Build the desktop app.

​
Run the checks before a pull request

Run the focused tests for your change first, then the fast checks of every app you touched. None of these checks need a database or containers. To run a single test:
  • Web: pnpm --filter @linger/web test <test-file>
  • node-services: pnpm --filter @linger/node-services exec vitest run <test-file>
  • TeamHub package: cd apps/teamhub && go test ./internal/<pkg>

​
Run the TeamHub integration tests

Run the integration tests when a change touches database, process, concurrency, or recovery behavior that a unit test cannot prove. Integration tests need Docker. Unit tests do not. The shared test database is one PostgreSQL that later runs reuse, with a separate database per test. Set TEAMHUB_TEST_DATABASE=isolated to ignore it for one run.

​
Verify user journeys by hand

Some changes need a check in the running product. Record the revision, the steps, and what the user could observe. A cross-build does not verify a real Windows desktop. A simulated failure does not verify a successful wiki publication.

​
Prepare the pull request

Keep one pull request to one change. Describe what changed, why, and how you verified it. The pull request template lists what reviewers expect.
  • Commits follow Conventional Commits, for example fix(web): keep the composer draft across Rooms. A commit hook runs commitlint and formats staged files.
  • Docs in the nearest AGENTS.md or README change in the same pull request when behavior, ownership, contracts, or file paths change.
  • Language is English for code, comments, docs, tests, and user-facing strings.
  • Secrets stay in the ignored root .env. Never commit them.
By contributing, you agree to the contributor terms in the repository’s LICENSE. The producer may make the license stricter or more relaxed. Your contributed code may be used commercially, including in the producer’s cloud business.

​
Keep learning

Architecture overview

See how the services fit together and where each one lives.

Environment variables

Look up each setting in .env.

Build a Skill

Add or version a built-in Skill.

CLI reference

Look up linger, linger-computer, and teamhub commands.