georg.dev

Sandbox your GitHub Copilot CLI on Linux

Mon, 09 Feb 2026 00:00:00 GMT

TL;DR

This article shows how to set up rootless Docker on Linux for running GitHub Copilot CLI in isolation
Build a custom Ubuntu container image with GitHub Copilot CLI pre-installed
Mount your project directory into the container so you and Copilot share the same workspace
Configure persistent authentication so you don't need to log in every time
Launch ephemeral containers for different projects with a simple script
Copilot gets full access to your project directory but can't touch the rest of your system

GitHub Copilot CLI is a powerful AI coding assistant, but unlike Claude Code or Codex, it has no built-in sandboxing. If you want to be safe, you have to constantly approve every file read/write outside the project directory, and every new command execution. You might want to enable --yolo mode and let the agent work uninterrupted, but that’s risky as Copilot could easily go rogue.

The solution: run Copilot CLI in an isolated sandbox. Docker is perfect for this. Full filesystem access inside, zero risk to your host machine.

If you’re on macOS or Windows with Docker Desktop, you’re in luck. Just use the experimental docker --sandbox command and you’re done. However, if you’re on Linux, docker --sandbox isn’t available.

This guide shows you how to set up a similar isolation using rootless Docker. You’ll get a sandboxed environment for Copilot CLI without needing Docker Desktop.

Disclaimer: Unlike docker --sandbox, this approach doesn’t restrict network traffic. Your agent can communicate freely with the internet, which creates the risk of data exfiltration.

Sneak-peak of what you’ll going to build

With this setup, you’ll be able to launch Copilot CLI in a sandboxed container with a single command.

For example, let’s say you have a project at ~/projects/my-project. You can just run:

./copilot-sandbox.sh ~/projects/my-project

This will do the following:

Start GitHub Copilot CLI in a sandboxed environment
Give Copilot access to your project folder but nothing else on your system
Destroy the sandbox when you exit again, but remember the authentication so you don’t have to log in next time
Allow you to run multiple sandboxed agents for different projects in parallel

Let’s go!

1. Install rootless Docker on Linux

Rootless Docker means the Docker daemon runs as your regular user (not root), and containers are isolated using user namespaces. The containers think they’re running as root inside, but they’re actually mapped to your unprivileged user ID on the host. This is much safer than regular Docker.

1.1 Install prerequisites

sudo apt-get update
sudo apt-get install -y uidmap dbus-user-session

What’s happening here:

uidmap provides the newuidmap and newgidmap tools that allow your user to map a range of user IDs
dbus-user-session ensures systemd user services work correctly
These tools let Linux create “fake” root environments inside containers while keeping everything unprivileged on the host

1.2 Configure subordinate UIDs/GIDs

Check if you already have subordinate UID/GID ranges:

cat /etc/subuid
cat /etc/subgid

If you see lines like, you’re already set up. Go to the next step (1.3).
```
yourusername:100000:65536
```

Otherwise, if these files are empty or your user isn’t listed, add ranges:

sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER

What this means:

Your user gets a range of 65,536 “fake” UIDs (100000-165535)
When a container thinks it’s running as UID 0 (root), it’s actually mapped to UID 100000 on your host
This means even if a container is compromised, the attacker only has access to these mapped, unprivileged UIDs

1.3 Install Docker CE (if not already installed)

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

1.4 Install rootless Docker extras

sudo apt-get install -y docker-ce-rootless-extras

What’s in this package:

dockerd-rootless-setuptool.sh - the setup script
rootlesskit - creates the user namespace and handles networking
slirp4netns - provides user-mode networking (no root needed)

1.5 Disable the root Docker daemon

sudo systemctl disable --now docker.service docker.socket

Why:

You don’t want the root daemon running alongside rootless
This prevents confusion and conflicts

1.6 Initialize rootless Docker

dockerd-rootless-setuptool.sh install

What this does:

Checks prerequisites (subuid/subgid)
Creates systemd user service files in ~/.config/systemd/user/docker.service
Starts the Docker daemon as your user
Sets up the Docker socket at /run/user/$(id -u)/docker.sock

1.7 Configure your shell

Add to ~/.bashrc:

export PATH=/home/$USER/bin:$PATH
export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock

Then reload:

source ~/.bashrc

Why:

The Docker CLI needs to know to talk to your user’s socket, not the system socket
The binaries are installed in your home directory, not system paths

1.8 Enable the service to start on boot

systemctl --user enable docker
sudo loginctl enable-linger $USER

What enable-linger does:

Normally, user services stop when you log out
enable-linger keeps your user’s systemd instance running even when you’re not logged in
This means your Docker daemon persists across logins

1.9 Verify installation

docker run hello-world

Check the output in the terminal. You should see a message confirming Docker is working.

2. Building your Copilot sandbox image

Now let’s create myorg/copilot-sandbox:latest with Copilot CLI pre-installed.

2.1 Create a Dockerfile

mkdir ~/copilot-sandbox
cd ~/copilot-sandbox
nano Dockerfile

Put this in the Dockerfile:

FROM ubuntu:22.04

# Prevent interactive prompts during installation
ENV DEBIAN_FRONTEND=noninteractive

# Install basic tools and Node.js repository
RUN apt-get update && apt-get install -y \
    curl \
    git \
    nano \
    ripgrep \
    ca-certificates \
    gnupg \
    && mkdir -p /etc/apt/keyrings \
    && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
    && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list

# Install Node.js 22
RUN apt-get update && apt-get install -y nodejs

# Install GitHub Copilot CLI
RUN npm install -g @github/copilot

# OPTIONAL: Install any other dependencies your devleopment setup
# might require (Python, Java, etc.)

# Clean up to reduce image size
RUN apt-get clean && rm -rf /var/lib/apt/lists/*

# Set working directory
WORKDIR /workspace

# Default command: bash
CMD ["/bin/bash"]

Important: make sure you also add all other packages your developer setup might require to this file.

2.2 Build the image

docker build -t myorg/copilot-sandbox:latest .

This will take a few minutes. The -t flag tags it with the name you want.

3. Running a session with the sandboxed Copilot CLI

You’ll use ephemeral containers (destroyed on exit with --rm) but persist authentication data in named Docker volumes. This means:

Each container is fresh and clean
You can work on different projects easily
You only have to authenticate once (auth data persists in volumes)
No container clutter building up

3.1 Create a persistent volume for authentication

First, let’s create the volume that will store authentication data:

docker volume create copilot-sandbox-root

What this does:

Creates a named volume called copilot-sandbox-root
This volume persists on your system even when containers are destroyed
You’ll mount this to /root inside the container where Copilot CLI usually stores its auth tokens

3.2 Create the launch script

nano ~/copilot-sandbox.sh

Put this in the file:

#!/bin/bash

# Get project directory from first argument, default to current directory
PROJECT_DIR="${1:-.}"

# Resolve to absolute path
PROJECT_PATH="$(realpath "$PROJECT_DIR")"

# Check if project directory exists
if [ ! -d "$PROJECT_PATH" ]; then
    echo "Error: Directory $PROJECT_PATH does not exist"
    exit 1
fi

echo "=========================================="
echo "Launching Copilot sandbox container"
echo "Project: $PROJECT_PATH"
echo "=========================================="
echo ""
echo "Inside the container, run 'copilot' to open the CLI."
echo ""

# Run the container
docker run --rm -it \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  -v "$PROJECT_PATH":/workspace:rw \
  -v copilot-sandbox-root:/root \
  myorg/copilot-sandbox:latest \
  bash

Flag explanations:

--rm: Automatically removes the container when you exit (keeps system clean)
-it: Combined flags:
- -i (interactive): Keeps STDIN open so you can type commands
- -t (pseudo-TTY): Allocates a terminal for proper interactive experience
--cap-drop ALL: Drops all Linux capabilities (prevents privileged operations)
--security-opt no-new-privileges: Prevents privilege escalation via setuid/setgid
-v "$PROJECT_PATH":/workspace:rw: Mounts your project directory to /workspace with read-write access
-v copilot-sandbox-root:/root: Mounts the persistent volume to /root (where auth data is stored)
myorg/copilot-sandbox:latest: The image you built earlier
bash: Starts an interactive bash shell

3.3 Make the script executable

chmod +x ~/copilot-sandbox.sh

4. First-time authentication

4.1 Launch your first session

~/copilot-sandbox.sh ~/projects/my-project

You’re now inside a container with a bash prompt. Your project files are available at /workspace.

4.2 Authenticate with GitHub Copilot CLI

Inside the same container, run:

copilot

What happens:

Copilot CLI starts for the first time
It prompts you to authenticate with /login
Type /login and press Enter
Follow the browser authentication flow
Sign in with your GitHub account that has Copilot access
Token is saved to the copilot-sandbox-root volume

4.3 Exit the Container

exit

The container is destroyed, but your authentication data remains in the copilot-sandbox-root volume and persists across container sessions.

Usage examples

Example 1: Run from your project directory

cd ~/projects/my-project
~/copilot-sandbox.sh

If you’re already in the project folder, you can just run the script without arguments. It will use the current directory if no argument is provided.

Example 2: Run multiple projects in parallel

Terminal 1:

~/copilot-sandbox.sh ~/projects/project-a

Terminal 2:

~/copilot-sandbox.sh ~/projects/project-b

Terminal 3:

~/copilot-sandbox.sh ~/projects/project-c

Each container is isolated, fresh, and destroyed on exit. Your authentication persists across sessions.

Wrapping Up

You now have a fully isolated environment for running GitHub Copilot CLI on Linux. Fresh containers for each project, persistent authentication, and strong security boundaries. Copilot can modify files in /workspace freely but can’t touch the rest of your host system.

Remember: the container has full network access. The agent can send data to external servers. Don’t run untrusted code or work with sensitive credentials inside the container unless you’re comfortable with that risk.

If you want a GitHub-native workflow on top of this, have a look at kipp•punk. It is self-hosted, works with different coding-agent harnesses, and keeps clear control boundaries: you approve the scope, review the PR, and decide what ships.

If you found this useful, follow me on X, BlueSky, or LinkedIn for more technical deep dives like this.

AI-driven unit testing with GitHub Copilot

Mon, 01 Dec 2025 00:00:00 GMT

TL;DR

AI can write unit tests for you, but a prompt like "write tests for this code" produces garbage.
This article shows an AI workflow that actually works using GitHub Copilot's instructions and prompt files.
You decide which test cases to implement, AI writes them, you review the results.
The article includes a ready-to-use prompt file and an example repository.

Unit tests are a pain to write. They keep your codebase maintainable, sure, but that doesn’t make writing them less tedious. After all, you’ve just implemented the feature and your code works. But now you have to revisit everything and write tests for it.

The obvious idea: why not let AI handle it? It excels at this type of tedious, repetitive task anyway.

But if you just prompt an LLM to “write tests for this code”, you’ll get more garbage than you’d expect, e.g., useless test cases, tests tied to implementation details, and even worse, false positives.

This article shows you a better way: an AI workflow that uses GitHub Copilot to do the tedious part of the work for you while you maintain control over test cases and quality.

(TDD aficionados: I see you. There’s something for you at the end as well.)

The problem with AI-generated unit tests

Before we talk about the solution, let’s understand the problem first. Why does AI perform so badly when prompted to write unit tests?

LLMs are expensive to run and context windows are limited. Every new conversation with GitHub Copilot starts fresh with no prior knowledge. Copilot also has to make smart choices about how much of your codebase to load into context. Even you might struggle to derive domain logic from a codebase you’re seeing for the first time. Imagine you could only read parts of it.

Current AI is also bad at logical thinking and generalization. It has difficulty deriving intent from code alone and tends to focus on testing the code rather than the underlying requirements. This leads to shallow tests and false positives. AI also struggles with granularity and implements tests for the same requirement repeatedly. Worst of all: sometimes it gets so fixated on making tests pass that it modifies production code.

TL;DR, current AIs:

don’t have a good overview of the codebase,
struggle with understanding the business logic,
produce shallow and redundant tests,
produce false-positive tests,
can modify production code instead of fixing failing tests.

That’s a lot of limitations. But there’s a way to work around them.

Solving AI assistant shortcomings

All you need to mitigate these limitations is good instructions for the AI, proper context engineering, and minimal human oversight at the right moments.

Here’s what it looks like:

fig.1 — the human-in-the-loop workflow

You start by running the workflow prompt and telling GitHub Copilot which files to test.

The AI loads all relevant files and instructions into context: repository overview, business domain, architecture, conventions. It reads the files it should test and gathers information while focusing on the underlying business logic. If something is unclear, it asks.

Once ready, the AI proposes test cases. You review them, add new ones, modify or remove existing ones, or approve the proposal. This lets you guide the AI with minimal intervention.

After your approval, the AI gets to work. You can start a new feature, check Slack, get coffee, whatever. GitHub Copilot generates tests for all approved cases, runs them, and iterates until they all pass.

When done, the AI notifies you with a summary. You review the tests, provide feedback if needed, and accept the changes.

You’ll see this whole process in action in a video later. First, let’s set it up.

Setting up the workflow

The setup requires some configuration, but each step is straightforward. I also created an example repository you can use to get started quickly. Here’s what you need to do:

Configure Copilot instructions. Copilot performs much better when it understands your project’s conventions, domain, and architecture. Create a copilot-instructions.md file to provide such general context to the AI (see example).
Add code generation instructions for tests. Code generation instruction files are provided to Copilot right when it’s about to generate code. This is the ideal place to give the AI guidance on writing tests in your codebase (think: naming conventions, testing libraries, mocking patterns, etc.). Create a .instructions.md file with a file pattern that matches your test files and instructions for your specific codebase and testing framework (see example).
Enable the todo list tool. LLMs typically struggle with multi-step workflows. That’s why GitHub Copilot’s manage_todo_list tool lets the AI track and execute workflow steps. Make sure it’s enabled by following this guide.
Configure auto-approval. The workflow needs to run some terminal commands autonomously without constantly asking for permission. For VS Code, set up .vscode/settings.json to auto-approve certain commands (see example). If you’re using a JetBrains IDE, there’s a similar setting. Make sure to be smart about this list and only allow commands that don’t pose a risk if the AI goes astray.
Create the workflow prompt. This file contains the full workflow description. In the folder .github/prompts, create the file write-unit-tests.prompt.md and add the following content:

---
mode: 'agent'
description: 'Generate unit tests for the provided code.'
---

Your task is to write unit tests for the provided code.

Use the `manage_todo_list` tool to keep track of the following tasks:

1. Analyze context files:
  - Read all files that have been provided as context.
  - For each file, briefly summarize its purpose and identify the key business logic and edge cases that require testing.
  - If anything about the business logic is unclear, ask the user to provide more information.
2. Propose test cases:
  - Based on your analysis, propose a concise list of test case titles (grouped by file/module), e.g.:
    > A. `MyComponent.tsx`:
    >   1. should display a greeting when showGreeting is true.
    >   2. ...
    > B. `useHelloWorld.ts`:
    >   1. should ...
  - Only propose tests for business logic that is relevant and actually requires testing.
  - Ask the user to review and approve or edit this list.
  - Do not proceed to implementation until the user explicitly approves the final list.
3. Implement approved tests:
  - Implement exactly the test cases approved by the user. Do not add unapproved tests and do not omit any approved test.
4. Run tests and iterate until green:
  - Run all tests that you added.
  - If any test fails, first verify whether the failure is due to the test (not the product code).
    - If the failure is due to the test, fix the test.
    - If the failure appears to be a product issue, ask the user how to proceed. Do not modify production code without asking the user for consent.
  - Re-run until all tests pass.
5. Check and fix project quality gates:
  - Run type checks, linters, and any formatting tools configured in the project.
  - If any check fails, first verify whether the failure comes from one of the test files you edited or if it comes from unrelated code.
    - If it comes from one of the test files you edited, fix the error.
    - If it comes from unrelated code, ignore the error.
  - Re-run checks until they are clean or until only unrelated files cause issues.
6. Final verification and report:
  - Finally, run the full test suite. Confirm that all newly created tests pass.
  - Provide a very brief summary of what you did.

Rules and constraints:
- You are only done if **all** the steps have been completed successfully. Otherwise, you must continue.
- If critical information is missing, always ask the user.

Using the workflow

Here’s how to run the workflow once everything is configured. The video below shows the workflow in action. You can also follow the written steps underneath.

Your browser does not support the video tag.

fig.2 — the workflow running in VS Code

Start the workflow.
1. Open VS Code and start a new chat in the Copilot chat window.
2. Select a capable model. In my experiments, GPT-4o wasn’t quite up for the task and I usually used Claude Sonnet 4.5, but it ultimately depends on your codebase.
3. Click the Add Context… button in the Copilot chat input field. Select the files you want the AI to write unit tests for.
4. Type /write-unit-tests into the Copilot chat.
Review proposed test cases. The AI will now start gathering context. Once it’s done, it will propose the unit test cases. Carefully review them.
Approve test cases. Type into the chat window which test cases you’d like to have implemented. You can reference them by number, like “A1, A5, B2”.
Let the AI work. The AI will get to work. If you have a good allow-list for tool calls, you shouldn’t be bothered until it’s done.
Final review. After a while, the AI will ask for final approval. Carefully review the written tests and provide feedback where necessary. If you’re happy with the results, accept the changes.

If you want to try out the workflow without setting everything up yourself, feel free to clone the example repository and follow the steps above.

Discussion & recap

Once everything is set up properly, this workflow can be quite powerful. You can one-shot an entire test suite and move on to other work while the AI handles the tedious parts. Getting there takes some trial and error with your instruction files, but I found the experimentation process surprisingly rewarding once results started coming together.

That said, there’s a tradeoff worth considering. Normally, writing tests after code serves as a quality review step. You catch issues while thinking through edge cases. This workflow skips that. The AI can catch bugs during test generation (it happened to me several times) but I wouldn’t count on it. You still need to review the generated tests carefully, and depending on how well-tuned your setup is, this might save you significant time or barely make a dent.

For TDD enthusiasts: you can invert this workflow. Write the tests first and let the AI generate the code to make them pass. Same configuration steps, same human checkpoints, just reversed. If you create a TDD version of the prompt file, I’d love to see it.

If you like this kind of human-in-the-loop workflow, have a look at kipp•punk. It applies the same pattern to GitHub issues and pull requests: the agent refines the task with you, implements it, opens a PR, and reacts to review comments while you stay the quality gate.

Conclusion

Asking an AI to “write tests pls” won’t magically produce quality unit tests. But with the right workflow, proper context, a structured prompt, and two deliberate human checkpoints, you can hand off the tedious work while you control which tests are written and provide the common sense the AI lacks.

It’s not zero-effort. You need to set up instruction files and tune the workflow to your codebase. But you can use the prompt file above and the example repository to get started quickly. If you run into issues or have questions, reach out. I’m curious to hear how this works for different codebases.

I share more coding and AI development tips on X, BlueSky, and LinkedIn.

Better Context, Better GitHub Copilot

Mon, 21 Jul 2025 00:00:00 GMT

GitHub Copilot is only as good as the context you give it. Without proper guidance, you’ll waste time correcting off-target recommendations or explaining basic project details repeatedly.

A well-crafted copilot-instructions.md file provides consistent, project-specific context for every prompt. You get:

Better first drafts
Fewer corrections
Faster work in Agent mode

Let’s examine how to build an effective instructions file.

Don’t vibe your copilot-instructions.md

I researched on GitHub and in developer communities to see how people write their copilot-instructions.md files. The majority either let an LLM generate it without proper project context, or copy/paste generic instructions from others.

The result is mostly generic AI slop. Don’t do that.

The copilot-instructions.md file becomes part of every Copilot request’s context window. Since it’s included with every prompt, its content directly impacts the quality and relevance of all suggestions. Research shows that irrelevant information can drastically reduce response quality or, worse, send the AI astray entirely. Therefore, avoid generic sentences that just waste tokens and instead prioritize project-specific details Copilot can’t immediately infer from your code alone, e.g. architectural patterns, domain terms, and non-obvious constraints.

But first, let’s set it up.

Setting up your copilot-instructions.md

You have two starting options: writing it yourself by filling out the skeleton below or have Copilot Agent bootstrap it for you and then edit the file. Due to the reasons above, I recommend using the former option.

Option 1: Write the file yourself (recommended)

In your repository root, create the folder .github if it doesn’t exist already. Then, create an empty file in that directory called copilot-instructions.md and copy/paste the following content into the file:

## Summary
<!-- brief summary of the repository -->

## Terminology
<!-- list of domain specific terms with their explanation -->

## Architecture
<!-- short summary of the architecture -->

## Task planning and problem-solving
<!-- the most important problem-solving guidelines -->
<!-- e.g. "plan the task before writing any code" -->

## Coding guidelines
<!-- the most important coding guidelines -->

Option 2: Generate the file with the Copilot Agent

Alternatively, you can let GitHub Copilot Agent generate the file with the latest VSCode release (@pierceboggan thanks for the heads-up):

fig.1

This will provide you with a usable starting point but some information will most likely be off or even incorrect and some will be missing. Therefore, after creating the file, go over each sentence, improve the existing content iteratively, and add your own.

Next, let’s cover what to include.

What to include in your instruction file

I researched the most frequently used sections in copilot-instructions.md files to identify effective practices. Use these as inspiration, but tailor them to your project and Copilot usage. If you use Copilot to only generate unit tests for a React repository, your instruction file will look very different from someone who only uses it to generate new features for Java services.

Summary

Summarize your repository briefly, e.g.:

This repository contains the source code for a Pokémon card 
trading platform's web app, enabling online card trading.
It manages trade processing and card inventory tracking.

Terminology

List domain-specific terms with explanations, e.g.:

- trade - User’s trade request (card, condition, price).
- stock - Inventory of Pokémon cards for tracking and listing.
- queue - List of pending trades, prioritizing user offers.

Architecture

Describe the architecture, focusing on non-obvious details. This section is most effective when you explain the “why” behind your architectural decisions, not just the “what”. Also, make sure to reference important files:

The React frontend interacts directly with Supabase
for database operations, user authentication, and 
real-time trade updates, while integrating with 
the PokeAPI for Pokémon data. Supabase was chosen for its
real-time capabilities and PokeAPI for its generous 
rate limits.
- `supabaseClient.js` - Supabase client & authentication.
- `realTimeTradeSubscriptions.js` - Manages trade updates.
- `pokeApiIntegration.js` - Interacts with PokeAPI.

Task planning and problem-solving

LLMs struggle with common sense and problem-solving. To improve Copilot’s task accuracy, include step-by-step instructions in this section. I noticed better results when telling the LLM to plan before coding. Some models drown problems in code until they work (Claude 👀). Instructing Copilot to reuse existing code helps.

- Before each task, you must first complete the following steps:
  1. Provide a full plan of your changes.
  2. Provide a list of behaviors that you'll change.
  3. Provide a list of test cases to add.
- Before you add any code, always check if you can just re-use
  or re-configure any existing code to achieve the result.

Model-specific instructions

If you find yourself mostly working with the same AI model, you probably notice some recurring flaws or annoyances. Use this section to nudge the LLM in your desired direction. For example, if the AI tends to be over-comprehensive, use something like this:

- Always focus on simplicity and precision and not comprehensiveness.
- When writing tests, focus on the happy path and only the most 
  important edge cases.
- Before adding a new test, always make sure that a similar test 
  doesn't exist already.

Language-specific instructions

Add language specific rules or use code generation instructions (at the time of writing only available for VSCode).

Try 10xrules.ai to generate these quickly.

Coding Guidelines

Specify coding styles not caught by linters. Include examples where needed.

What else?

These are just the most commonly useful examples. Add other relevant instructions specific to your project. For instance, here are two Reddit posts that contain some additional categories which can be used as further inspiration: 1, 2.

But first, let’s ensure your instructions follow an effective writing style.

How to write your copilot-instructions.md

Whatever you finally decide to include in your copilot-instructions.md file, I recommend following this writing tips. They ensure your instructions are clear and actionable for Copilot:

Use consistent imperative voice.

<!-- Don't ❌ -->
When fixing a bug, it helps to write a failing test first.
  
<!-- Do ✅-->
When fixing a bug, always write a failing test first.

Don’t be generic. Advice should be specific and actionable.

<!-- Don't ❌ -->
Write maintainable code.
  
<!-- Do ✅ -->
Always follow the DRY principle and avoid code duplication.

Instead of just telling the AI what not to do, tell it what to do instead.

<!-- Don't ❌ -->
Don’t use hard-coded numbers.

<!-- Do ✅-->
Avoid hard-coded numbers and use shared constants instead.

Don’t add style guides that your linter catches anyway. Less is more.

<!-- Don't ❌ -->
- Follow the ESLint rule `default-case`.
- Always add a `default` case at the end of a `switch` statement.
  
<!-- Do ✅ -->
<!-- Let your linter catch these issues instead. -->

Don’t link to external resources in the instructions.

<!-- Don't ❌ -->
The API endpoint to retrieve data about a specific Pokémon 
is defined [here](https://pokeapi.co/docs/v2#pokemon).
  
<!-- Do ✅-->
To retrieve data about a specific Pokémon, send a `GET` request
to `https://pokeapi.co/api/v2/pokemon/{id or name}/`.

Include examples where necessary, especially when writing about patterns.

<!-- Don't ❌ -->
Prefix boolean variables with an appropriate verb.
  
<!-- Do ✅-->
Prefix boolean variables with an appropriate verb, e.g.
`isLoading`, `hasPermissions`, `matchesFilter`.

Bonus: Boost the Agent mode

GitHub Copilot’s Agent mode runs tasks in the background while you focus elsewhere. Ideally, you give it an instruction, and it completes code, tests, and checks automatically. In reality, Copilot often changes code and stops, needing prompts to run linters or tests. Adding upfront instructions can automate this process.

For this, add to the task planning section of your copilot-instructions.md:

If you add new code or change existing code, always verify that
everything still works by running *each* of the following checks:
1. `npm run lint` to run the linter.
2. `npm run test:unit` to run the unit tests.
3. `npm run test:e2e` to run the e2e tests.

Complete the task only after all checks pass.

Copilot adds changes, runs the commands, assesses output, and iterates until all errors are fixed:

fig.2

By default, Copilot requires your approval for each tool usage, but in VSCode, you can add "chat.tools.autoApprove": true to your settings.json to enable auto-approval and go full vibe-coding.

If you want to take the same idea further, have a look at kipp•punk. It keeps the agent loop in GitHub: the agent refines the issue with you before implementation, opens a PR, and reacts to review comments. Same principle, just applied to the full workflow instead of a single prompt.

Wrapping up

A tailored copilot-instructions.md saves you time and improves Copilot’s output. Focus on specific, actionable instructions to guide its suggestions. Use the tips above to craft a file that fits your project and let me know how it goes! Did I miss any tips you use for copilot-instructions.md?

For more tips like these, follow me on X or BlueSky.

How (not) to find the unsung heroes of JavaScript

Wed, 26 Feb 2025 00:00:00 GMT

fig.1

You’ve seen this xkcd comic — the one where the entire internet runs on a project some random developer has been thanklessly maintaining since 2003. It’s funny because it’s true. And in [insert current year here], it’s still true.

I’m Georg, a data scientist turned software engineer working mostly in the JavaScript/TypeScript ecosystem. I wanted to fix the problem behind the comic — or at least find those invisible maintainers holding up the ecosystem with duct tape and caffeine. You probably depend on their work every day. I definitely do.

But here’s what happened instead: I found thousands of useless npm packages, a blockchain protocol gone wrong, and a lesson in why noble goals aren’t enough. Let’s talk about good intentions, bad incentives, and why your code — and your career — are built on a house of cards.

The search for JavaScript’s invisible maintainers

If you ask, “Who here deserves funding for their open-source work?” everyone raises their hand. That’s the problem. The loudest voices — or the savviest marketers — aren’t always the ones keeping your code from collapsing. After all, most open-source maintainers have better things to do than self-market, like fixing bugs, reviewing PRs, and keeping the lights on.

So I tried something simple: ignore the noise. Instead of listening to who was asking for money, I wanted to see what the ecosystem actually depended on. JavaScript’s dependency graphs are public, after all. How hard could it be?

I downloaded npm’s metadata dump — every package, every dependency, every maintainer — and ran the numbers. The goal: find projects with high dependents but low visibility. Think libraries like ipaddr.js, a utility for manipulating IP addresses with 44 million weekly downloads, or long, a library for working with 64-bit integers with 28 million weekly downloads. These tools are everywhere, but their maintainers often go unnoticed — working quietly behind the scenes to keep the ecosystem running.

The logic was sound. If a package has thousands of dependents but just one maintainer and almost no contributors, that’s probably our famous Nebraskan. If it’s a transitive dependency — something your code uses indirectly, three layers deep — even more so.

At first, it worked. I did not only find well-known packages but also others like anakjalanan, nitroteh, and acertea — each with thousands and thousands of dependents, a single maintainer, and names I’d never heard of. These had to be the unsung heroes.

Then I checked the repositories.

Some led me to completely empty codebases. Others only contained bootstrapped Next.js or Node.js applications without any additional functionality. They weren’t just unmaintained. They were literally useless.

fig.2

What’s going on here? Why would thousands of projects depend on empty repositories and abandoned forks?

But then I noticed that all those repositories had one thing in common: a file called tea.xyz.

This is why we can’t have nice things

Meet the tea Protocol — a blockchain-based attempt to fix open-source funding. Their goal was similar to what I was trying to do, but with a cryptocurrency on top: use the dependency graph to measure a package’s impact and automatically reward maintainers with tokens. Simple.

Too simple.

tea’s “Proof of Contribution” model tied funding to dependency counts. The more projects that depend on you, the more you earn. Sounds fair — until you realize how easy it is to fake a dependency.

Suddenly, those empty repositories made sense. Spammers flooded npm with trivial packages, each containing a tea.xyz file. By artificially inflating their dependency counts, they could trick the protocol into paying them for “impact.”

Even worse, some scammers tried to sneak their own tea.xyz file into widely used open-source packages, like node-bin-gen, via a pull request. The maintainers shut it down, but not before uncovering countless similar PRs targeting other established repositories. The same abuse appeared in other package registries like PyPI and RubyGems, with useless packages clogging up the ecosystem.

fig.3

To tea’s credit, they reacted quickly. By mid-2024, they added mandatory registration and guardrails against spam. npm uploads returned to normal. But the damage was already done: the NPM registry is still littered with those packages.

fig.4

Good intentions, bad incentives

Goodhart’s Law states: “When a measure becomes a target, it ceases to be a good measure.” In simpler terms, the moment you tie money to a metric — like GitHub stars, dependency counts, or downloads — you create an incentive to optimize for the metric, not the underlying value.

tea Protocol learned this the hard way. And keep in mind, when this happened, tea wasn’t even a major funding allocator yet. Imagine the chaos if large organizations had poured hundreds of thousands of dollars into the system.

Fix one loophole, and another emerges. This isn’t unique to tea — Gitcoin’s quadratic funding battles Sybil attacks, App Store rankings get manipulated constantly, and even academic citation metrics are gamed. Platforms like GitHub Sponsors and thanks.dev take a different approach, enabling companies to fund projects they depend on — even transitive dependencies. While less prone to manipulation, they’re not immune. Developers can still game the system by fragmenting code into shallow dependencies. Any funding model based on automation will eventually be exploited.

But let’s assume, for a moment, that you find the perfect metric after all. Let’s say you invent the ungameable tea Protocol 2.0. Now what?

Where does the money come from?

tea’s tokenomics hinge on the price of its cryptocurrency. But if the token’s only utility is to be paid out to maintainers — not to be spent — there’s no real demand. Its effective value is zero. The only way to keep the price above that is to artificially counterbalance the excess supply with enforced staking and built-in deflation, creating demand through financial speculation.

But sustainable, long-term open-source funding can’t be built on speculation. At the end of the day, someone has to open their wallet and pay. Collectively, we seem to agree that it should be those who profit financially from open-source work. But that system has a major flaw.

Why aren’t companies funding?

Let me rephrase the question: Why should they? From a company’s perspective, the current system isn’t perfect, but it mostly works (👀 log4j), and best of all, it’s free. As a rational actor, there are only two reasons you’d fund open source:

The open-source project is core to your commercial product. But in this case, why fund it when you could just hire the maintainer? That way, you gain influence over the project and ensure it aligns with your business strategy.
Your product targets developers, and funding open-source projects is good PR. Sponsoring a trendy library or framework can win hearts in the developer community, which is great for hiring and marketing.

Don’t get me wrong — both are valid reasons. Funding with a personal incentive is still infinitely better than not funding at all. But neither scenario solves the Nebraska problem. Critical but unsexy projects stay underfunded.

So, what now?

The xkcd comic endures because it’s not a joke — it’s a reflection of reality. We’ve tried donations (too small), corporate sponsorships (too selective), and blockchain experiments (too gameable). None scale.

Maybe the answer isn’t technical. Maybe it’s a cultural shift — a recognition that open-source infrastructure is as vital as roads or electricity, and that we cannot neglect it in a time when the functioning of our entire modern world depends on it. Or maybe we’re stuck here, forever stacking yet another block on top of our Jenga tower.

What’s your take? Have you seen a funding model that actually works for invisible projects?

Let me know on X or BlueSky.

What is the Shadow DOM

Fri, 06 Sep 2024 00:00:00 GMT

TL;DR

Allows you to add additional subtrees to the main DOM.
Gives you style encapsulation natively supported by the browser.
Has an imperative API (JavaScript):
Has a declarative API (HTML) as well:

Missing style encapsulation

As a web developer, you’ve probably dealt with the headaches of missing style encapsulation. A single broad CSS selector can unexpectedly mess up the UI somewhere else on your site.

Adding third-party UI libraries only complicates things. Do their CSS class names clash with yours? Will their buttons break yours? Maybe.

The partial solution

Frameworks like Angular or Vue.js offer some form of component-based style encapsulation. Others, like React, let you choose from various style encapsulation libraries, such as styled-components.^[1]

However, their solutions typically offer only pseudo style encapsulation. Instead of fully isolating styles, they often just add prefixes or suffixes to CSS class names following some patterns that hopefully prevent name clashes.

Doesn’t this feel like a workaround? It does to me.

fig.1

Shadow DOM to the rescue

The shadow DOM attempts to fix the issue of missing encapsulation.^[2] It allows you to attach additional subtrees to the main DOM. With this API, you take an HTML node from your DOM and you simply attach a new subtree to it. We call the root node of this new subtree the shadow root. The neat part: styles don’t cross this shadow root.

fig.2

This means, the styles of your subtree don’t leak out into the main DOM. Also, the styles of your main DOM don’t affect the encapsulated content of the shadow DOM. Moreover, the same encapsulation also applies to browser events. An onclick event originating from the shadow DOM will not bubble up to the root of the main DOM. Instead, it will end at the shadow root.

How the shadow DOM works

There are two different ways how you can set up the shadow DOM. If you want to understand the concept better, take a look at the imperative API. Otherwise, feel free to jump ahead to the declarative API since that one is usually preferred by most developers nowadays.

Imperative API

Heads up: the imperative API does not work for server-side rendering (SSR). If you need SSR, use the declarative approach instead.

Let’s assume, we have a very basic HTML structure:

<body>
  <div><span>OUTSIDE the shadow DOM</span></div>
  <div id="host"></div>
</body>

Let’s go over this. Our DOM has a <body> element that contains two HTML nodes:

a <div> containing a <span> with the text OUTSIDE the shadow DOM,
a <div> with the ID host. This will be our host element to which we’ll attach the shadow DOM.

fig.3

Next, we get the reference to this <div> element and attach a shadow DOM to it. Then, for the sake of demonstration, we create another <span> and append it to the shadow DOM:

// get the reference to the div
const hostElement = document.querySelector("#host");

// attach a shadow DOM
const shadowDom = hostElement.attachShadow({ mode: "open" });

// create a new HTML node (just for demonstration)
const exampleElement = document.createElement("span");
exampleElement.textContent = "INSIDE the shadow DOM";

// append the new HTML node to the shadow DOM
shadowDom.appendChild(exampleElement);

Now, the new structure looks like this:

fig.4

If you inspect how this is rendered in the browser, you will see something like this:

<body>
  <div><span>OUTSIDE the shadow DOM</span></div>
  <div id="host">
    #shadow-root (open)
      <span>INSIDE the shadow DOM</span>    
  </div>
</body>

You can see all these steps together in this short animated diagram:

Your browser does not support the video tag.

fig.5

Declarative API

Heads up: the declarative shadow DOM has only recently been implemented in the last remaining browsers and is not fully adopted yet.^[3] If you use the declarative API, add the required polyfill to your application.^[4]

With the declarative shadow DOM API, you can do the same that we did in the imperative example above in plain HTML:

<body>
	<span>Outside the shadow DOM</span>
	<div id="host">
	  <template shadowrootmode="open">
	    <span>Inside the shadow DOM</span>
	  </template>
	</div>
</body>

Notice that we used the <template> element here. The reason for this is that the <template> element has its own mechanism for rendering its content. If you want to learn more about it, check out my template API article.

References

What is the Template API

Fri, 02 Aug 2024 00:00:00 GMT

TL;DR

The template API allows you to define reusable HTML content.
Everything inside a <template> element is part of the document but not rendered when the page is loaded.
However, you can extract the content and attach it to one or multiple other nodes where it will be displayed.
Use the <slot> element to allow for dynamic children.

The Problem

Re-using HTML within the same page can be tricky. Picture this: you have a complex piece of markup that needs to appear in several places on your page.

As a web developer, you might think, “No problem, I’ll just use a framework and create a component.”. But does it really make sense to bring in an entire library just to re-use some HTML? Shouldn’t re-using HTML be something that is supported natively?

Entering the <template> element.

How it works

Content inside a <template> element isn’t rendered when the page loads. However, it’s still part of the DOM and can be accessed via JavaScript. This lets you append this content to other DOM nodes and, thereby, making it reusable.^[1]

Consider the following HTML:

<body>
  <span>I'm visible.</span>
  <template id="my-template">
    <span>I'm initially <b>not</b> visible.</span>
  </template>
</body>

As you will see below, the content from inside the <template> is not visible. However, we can get the contents reference and append it to another node where it will be displayed:

// get the refence to the template
const template = document.getElementById('my-template');
// extract and clone the content from the template
const clonedContent = template.content.cloneNode(true);
// append the extracted content to another node
document.body.appendChild(clonedContent);

Now, the previously hidden content becomes visible. Try it out yourself:

fig.1 — live demo: rendering template content

This approach not only lets you render content dynamically, showing one component under specific conditions and another under different conditions.

It also allows you to attach the content to multiple nodes, enabling you to declare HTML once and use it multiple times across your page.

Using dynamic content

There’s one more thing to consider: dynamic content.

So far, we’ve only defined static content in the <template>, but what if we want to display dynamic content?

In React, you use the children property for that. In Angular, you use <ng-content>. With the template API, HTML introduces a native element: <slot>.^[2]

The <slot> element specifies the entry point for child nodes. Consider this HTML:

<template>
  <p>Is this the real life</p>
  <slot></slot>
  <p>Caught in a landslide</p>
</template>

<!-- and later -->
<bohemian-rhapsody>
  <p>Is this just fantasy</p>
</bohemian-rhapsody>

The rendered result will be:

fig.2 — live demo: rendering content into a slot

As you can see, the content put into the <bohemian-rhapsody> element got rendered into the <slot> element.

If you’re wondering where the <bohemian-rhapsody> element came from, check out my upcoming intro to custom elements.

References

What are Web Components

Sun, 16 Jun 2024 00:00:00 GMT

TL;DR

Web components are a web standard for native UI components.
Main idea: Write UI components once, use them across frameworks or standalone.
The web component standard consists of three specifications:
- HTML Templates
- Shadow DOM
- Custom Elements

Why Web Components

In 2014, the developer community was hyped: Google just released their new design system, Material Design. It looked fresh and exciting, promising a cohesive and well-thought-out experience. But what if you wanted to use it in your own web app? After all, Material Design is just the design specification.

You needed a component library.

If you were an Angular developer, you would install Angular Material. For React, you would use MUI, and for Vue, you would use Material Vue. Each individual framework needed its own library.

fig.1 — For Material Design 2, each framework still required its own component library since web components weren’t supported by all frameworks yet.

Think of all the effort wasted. Not only for the library creators who wrote and maintained the libraries but also for the library users who had to learn them. You could be an expert in Angular Material and still have to re-learn everything if you wanted to do Material Design in React.

But what if we could just write our UI component libraries once and use them in any web framework? This is exactly what happens with Material Design 3. How? With the power of web components.

fig.2 — For Material Design 3, only one component library is required, which is framework-agnostic thanks to web components. ^[1]

The Growing Significance of Web Components

Chances are, you’ve never used a web component yet, let alone created one. They are mostly popular among large companies needing framework-agnostic components, like Google, Microsoft, or Netflix. For example, GitHub has been a famous early adopter of web components.^[2] A more recent example is the Photoshop Web UI which was built by relying heavily on the web component framework Lit. In fact, Adobe built their whole Creative Cloud with the power of web components.^[3]

fig.3 — Screenshot of the Photoshop Web UI: Almost every element you see here is a web component.

According to the Google Chrome Platform status report, 15-20% of page loads and around 16% of URLs world-wide contain web components nowadays.^[4] This number has been steadily growing for years and the newly added web component support in React will likely increase it even further.

fig.4 — Google Chrome Platform Status: The number of URLs containing web components has been steadily rising from <0% in 2018 to around 16% in 2024.

What this means for you as a software developer is that even if you’ve never had any contact web components yet, you will encounter them sooner or later.

Defining a Standard

Even though we talk about the web component standard, it is actually the result of three different specifications:

HTML Templates: allows re-using HTML in the same document
Shadow DOM: Creates encapsulated DOM structures
Custom Elements: Associates HTML elements with JavaScript classes

Each specification already brings useful functionality on its own. Combined, they create re-usable and encapsulated UI components as a web standard: web components.

Curious to dive deeper?

Check out my upcoming articles where I’ll break down each of the three specifications: HTML Templates, Shadow DOM, and Custom Elements. Each article aims to equip you with the tools necessary to implement these technologies in your own projects. Keep learning!