ki-copilot/01-laien-einstieg.md

Kapitel 1

Einstieg ohne Copilot-CLI-Vorkenntnisse – vom Nullpunkt zur ersten Sitzung

Kern in einem Satz: GitHub Copilot CLI ist wie ein sehr kluger Junior in deinem Projektordner: Er darf erst arbeiten, wenn du dem Ordner vertraust – und du entscheidest bei riskanten Tools, bevor etwas schreibt oder die Shell öffnet.

---

1.0 Voraussetzungen prüfen

Bevor du installierst: du brauchst ein Terminal, ein aktives GitHub-Copilot-Abo und die Disziplin, Freigaben und Diffs zu lesen. Die Architektur (Modell vs. Harness, Agent-Schleife) steht in der Einleitung; hier wird es konkret.

Check	Warum
Terminal öffnen, cd, Befehl tippen	Lernpfad dieses Buchs ist CLI-first
Editor, Diff grob lesen können	Tag-1-Handgriff: Änderungen prüfen
Copilot-Abo aktiv; Org hat CLI nicht blockiert	sonst startet Auth/Session nicht sinnvoll
Internet	Login, Modelle, Updates

Optional: Terminal-Crashkurs in 3 Minuten

Was	macOS / Linux	Windows (PowerShell)
Terminal öffnen	Terminal.app / iTerm	PowerShell
In Ordner wechseln	cd ~/Arbeit/todo-cli	cd ~\Arbeit\todo-cli
Befehl starten	Text tippen, Enter	gleich
Datei anzeigen	cat README.md	Get-Content README.md

Merksatz: Der Cursor blinkt = bereit. Roter Fehlertext ist Information – Aufgabe C übt genau das.

---

1.1 Was ist GitHub Copilot CLI – in Alltagssprache

Stell dir vor, du hast einen Junior-Kollegen neben dir – einen allgemeinen Coding-Agenten im Terminal, der an deinem lokalen Projekt arbeitet (Trusted Directory), nicht nur an GitHub.com und nicht als reines Zeilen-Autocomplete. Konzept: Einleitung – allgemeiner Coding-Agent.

• Er kann Dateien lesen und schreiben
• Er kann Befehle ausführen (Tests, Installer, Git)
• Er fragt nach, bevor er etwas Riskantes tut – solange du das so lässt
• Er kennt dauerhafte Regeln, wenn du sie in Instructions legst – nicht weil er „sich erinnert“, sondern weil der Harness sie in den Kontext lädt

Das ist GitHub Copilot CLI. Kein Orakel. Ein Werkzeug mit Werkzeugen.

Chat vs. Agent (einfach):

Chat / Inline-Vorschläge	Copilot CLI (Coding-Agent)
Antwortet mit Text oder vervollständigt Zeilen	Antwortet und handelt (Dateien, Shell, optional GitHub)
Du kopierst Code hin und her	Er arbeitet im Projektordner – jedes Repo, das du vertraust
Wenig „darf ich?“	Permissions: freigeben, Session-Allow, ablehnen + Feedback
Oft an Editor-Surface gebunden	Terminal-Session; GitHub-Features sind stark, aber nicht Pflicht für sinnvolle Arbeit

Wie der Agent „handelt“: Du schreibst einen Auftrag. Das Modell plant Schritte und schlägt Tool-Aufrufe vor (lies diese Datei, führe pytest aus). Der Harness prüft Permissions, fragt dich bei Bedarf, führt aus und gibt das Ergebnis zurück. Dann plant das Modell den nächsten Schritt. Diese Schleife ist der ganze Alltag – und der Grund, warum enge Aufträge und Deny-Regeln so viel bewirken. Schema: Einleitung – Agent-Schleife.

Wie beim Junior: viel kann er, aber Scope setzt du, Diffs prüfst du, Produktion bleibt deine Entscheidung. Die drei Tag-1-Handgriffe: Scope formulieren, Freigabe lesen, Diff prüfen.

---

1.2 Installation

Kern: Ein Install-Weg reicht. Danach: copilot im PATH, Version prüfen, erst dann Login.

Voraussetzung laut Doku: aktives GitHub-Copilot-Abo. Unter Windows: PowerShell v6 oder höher für den Windows-Pfad; WSL ist voll unterstützt.

Du kannst installieren über npm (alle Plattformen), Homebrew (macOS/Linux), WinGet (Windows) oder das Install-Skript (macOS/Linux). Wähle den Weg, den du ohnehin pflegst – und bleib dabei.

npm (alle Plattformen)

Voraussetzung: Node.js 22 oder neuer.

npm install -g @github/copilot

Wenn in ~/.npmrc ignore-scripts=true steht:

npm_config_ignore_scripts=false npm install -g @github/copilot

Homebrew (macOS und Linux)

brew install --cask copilot-cli

WinGet (Windows)

winget install GitHub.Copilot

Install-Skript (macOS und Linux)

curl -fsSL https://gh.io/copilot-install | bash

Oder mit wget:

wget -qO- https://gh.io/copilot-install | bash

Optional: als root nach /usr/local/bin (| sudo bash), oder PREFIX / VERSION setzen – Details in der Installations-Doku.

Zu curl … | bash: Genau dieses Muster ist bei fremden URLs riskant. Hier vertraust du dem offiziellen GitHub-Installer einmal; im Projekt ordnest du fremde curl | bash-Vorschläge des Agenten unter Deny ein.

Prüfen

copilot --version

Hilfe außerhalb der Session:

copilot help

Häufige Stolpersteine

Symptom	Typische Ursache
command not found: copilot	PATH / Shell neu öffnen; bei npm globales Prefix prüfen
Alte Version nach Update	zweites Binary im PATH; which copilot / Get-Command copilot
Org-Policy-Fehler	Admin hat Copilot CLI deaktiviert – kein Install-Bug

---

1.3 Anmelden

Kern: Interaktiv OAuth (/login bzw. copilot login). Headless: fine-grained PAT mit Copilot Requests – kein classic ghp_.

Interaktiv (empfohlen für Tag 1)

1. In einen bekannten Projektordner wechseln (noch nicht ins Home).
2. copilot starten.
3. Wenn du nicht eingeloggt bist: /login in der Session oder vorher im Terminal:

copilot login

Für GitHub Enterprise Cloud mit Data Residency:

copilot login --host HOSTNAME

Der Device-Flow zeigt einen One-Time-Code, öffnet den Browser (oder du gehst zu https://github.com/login/device), du autorisierst GitHub Copilot CLI. Erfolg sieht ungefähr so aus: Signed in successfully as ….

In der Session kannst du später /user, /user list, /user switch und /logout nutzen (Labels und Verfügbarkeit: ? / Doku).

Headless / CI (nur Überblick – Vertiefung Kapitel 6)

Fine-grained Personal Access Token, Resource owner = dein persönliches Konto (nicht die Organisation), Account-Permission Copilot Requests, Repository-Zugriff so eng wie möglich.

Token exportieren (Platzhalter – nie echte Tokens committen):

export COPILOT_GITHUB_TOKEN=YOUR_TOKEN
# alternativ, niedrigere Priorität:
# export GH_TOKEN=YOUR_TOKEN
# export GITHUB_TOKEN=YOUR_TOKEN

Reihenfolge, in der die CLI Credentials sucht (vereinfacht aus der Auth-Doku):

1. COPILOT_GITHUB_TOKEN
2. GH_TOKEN
3. GITHUB_TOKEN
4. gespeichertes OAuth (Keychain / Fallback)
5. Fallback auf gh auth token, falls GitHub CLI eingeloggt ist

Token-Typ	Prefix	Unterstützt?
OAuth (Device Flow)	gho_	ja
Fine-grained PAT	github_pat_	ja – mit Copilot Requests
Classic PAT	ghp_	nein (laut Doku)

Achtung: Ein gesetztes GH_TOKEN / GITHUB_TOKEN überschreibt still ein OAuth-Login. Wenn ein anderes Tool diese Variablen setzt, nutzt copilot sie – auch wenn du „eigentlich“ per /login drin bist. Unbeabsichtigte Env-Vars wegräumen.

---

1.4 Trusted Directory – die erste Sicherheitsfrage

Starte immer im Projektordner, nicht in ~ und nicht in einem Downloads-Ordner voller fremder ZIPs.

cd /pfad/zu/deinem/projekt   # z. B. beispiele/todo-cli
copilot

Copilot fragt, ob du den Dateien in und unter diesem Ordner vertraust. Während der Session darf der Agent dort lesen, ändern und ausführen – sofern Permissions das im Detail erlauben.

{width=90%}

So ungefähr sieht die Frage im Terminal aus (Labels können mit Releases driften — die Entscheidung bleibt: vertrauen oder nicht):

{width=90%}

Die drei typischen Optionen (Wortlaut kann driften – die Entscheidung bleibt):

Option	Bedeutung
Yes, proceed	Vertrauen nur für diese Session
Yes, and remember this folder…	Dauerhaft merken – nur wenn der Ordner immer sicher ist
No, exit (Esc)	Session beenden

Später manuell:

/add-dir /path/to/directory

Arbeitsverzeichnis in der Session wechseln:

/cwd /path/to/directory

(laut Doku auch /cd)

Achtung: Starte Copilot CLI nicht aus deinem Home-Verzeichnis. Dort liegen oft SSH-Keys, Cloud-Creds, Browser-Profile und private Dateien. Trusted Directories sind die grobe Tür; Permissions sind die feinen Schlösser. Die Scope-Prüfung ist heuristisch – GitHub garantiert nicht, dass alles außerhalb absolut geschützt ist. Deshalb: enger Startordner, Diff lesen, Deny vor YOLO.

Unbekannte Ordner sind riskant: Ein Agent mit Shell kann Installer und Skripte auslösen, die im Repo liegen oder die er „hilfreich“ vorschlägt. Unbekannter Code + automatisierte Ausführung ≈ Skript von fremdem Stick – nur höflicher formuliert.

---

1.5 Erste Sitzung: drei sichere Aufgaben am todo-cli

15–25 Minuten, die den Rest des Buchs tragen.

Material: beispiele/todo-cli/. ZIP: unter https://books.maatini.space/projects/copilot-cli-harness/ (Material) in einen bekannten Arbeitsordner entpacken – oder Buch-Repository (siehe Einleitung). Im entpackten Paket bzw. Repo liegt der Pfad beispiele/todo-cli. Klein, bekannt, mit Tests. Nicht Produktion. Stabile Kernvorlagen (Instructions, enge Flags, Permission-Faustregeln) und die reine Start-Befehlsfolge stehen zusätzlich in Anhang A.

Setup vor dem ersten Prompt

cd beispiele/todo-cli

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest -q                          # sollte grün sein

Ohne venv und pip install scheitern Test-Aufgaben – das ist kein Copilot-Bug. Erklären ohne Edits geht auch ohne venv.

Session starten:

cd beispiele/todo-cli
# venv aktiv, falls du Tests laufen lässt
copilot

Trusted Directory bestätigen (Session oder merken – bei einem Übungsordner im Buch-Repo oft „remember“ ok, wenn du den Pfad kennst).

Gemeinsam für A–C: Scope eng + du bleibst Owner. Wenn der Agent trotzdem schreibt, obwohl du „nur erklären“ wolltest: Esc, Prompt enger wiederholen.

Aufgabe A – Code erklären lassen

Prompt:

Erkläre todo/store.py in einfachen Worten. Ändere noch nichts.

Ohne „ändere nichts“ springt der Agent oft in den Edit, bevor du verstanden hast.

Was du erwarten solltest: Lesende Zugriffe, dann eine Erklärung: JSON-Datei als Store, load / save / next_id, Default-Pfad unter dem Home (~/.todo-cli-book.json). Kein Schreib-Diff.

Warum diese Datei? store.py ist absichtlich simpel – und absichtlich unperfekt (kein atomares Write). Du siehst sofort, ob die Erklärung stimmt.

{width=90%}

Aufgabe B – kleiner, harmloser Fix

Prompt-Beispiel:

In todo/store.py: ergänze einen einzeiligen Docstring bei next_id,
der erklärt, dass die nächste freie ID zurückgegeben wird.
Nur diese Änderung. Danach pytest -q.

Was du tust:

1. Permission-Prompt für Schreiben: Yes (einmal), Diff lesen.
2. Shell für pytest: freigeben oder – wenn du üben willst – eng starten (siehe 1.6).
3. Tests grün? Gut. Diff unerwartet groß? Ablehnen oder zurückrollen.

Was ist ein Diff? Terminal oder IDE zeigt den Unterschied zur vorherigen Version (oft grün/rot). Du liest ihn bevor du große Änderungen akzeptierst – wie den Vorschlag eines Kollegen. Handgriff: /diff, git diff oder das Diff-Panel.

{width=90%}

Aufgabe C – Test laufen lassen und Fehler erklären

Falls etwas rot ist (oder du absichtlich einen Test kaputt machst):

Führe pytest -q aus. Wenn etwas fehlschlägt: erkläre die Fehlermeldung
in einfachen Worten. Noch keinen Fix schreiben, bis ich „fix“ sage.

Erfolg: Du siehst die Schleife – Shell-Tool, Output im Kontext, nächster Vorschlag – und du bremst mit Scope.

Optional eng starten

copilot \
  --allow-tool='shell(pytest)' \
  --allow-tool='shell(git status)' \
  --allow-tool='shell(git diff)' \
  --deny-tool='shell(rm)'

Deny schlägt Allow: selbst mit --allow-all-tools blockiert ein --deny-tool das genannte Tool. Das ist der Harness-Hebel „hart“, bevor du YOLO anfasst. Kompakte Baseline inkl. git push-Deny: Anhang A.3.

---

1.6 Permission-Prompt: Yes, Session-Allow, No

Sobald Copilot etwas ändern oder ausführen will, das riskant sein kann, kommt der Dialog. Typische Optionen (Wortlaut driftfähig):

Option	Wirkung
1. Yes	Dieses Tool diesmal – nächstes Mal wieder fragen
2. Yes, and approve TOOL for the rest of the session	Tool für den Rest der laufenden Session ohne Nachfrage (auch mit anderen Argumenten)
3. No, and tell Copilot what to do differently (Esc)	Abbrechen; du kannst Feedback geben, anderen Weg verlangen

Session-Allow-Risiko am rm-Beispiel:
Fragt der Agent rm ./tmp-note.txt und du wählst Option 2 für rm, darf er in dieser Session auch rm -rf … vorschlagen und ausführen, ohne dich erneut zu fragen. Session-Allow gibt das Tool frei, nicht den einen harmlosen Pfad.

{width=90%}

Im Terminal siehst du denselben Moment so (Labels können driften):

{width=90%}

Faustregeln Tag 1:

• Lesen / pytest / git status / git diff: oft Yes oder bewusstes Session-Allow
• rm, git push, Netzwerk-Installer, unbekannte Skripte: No oder nur Yes einmalig nach Lesen
• Unklar: No + kurzes Feedback („nur im Projektordner lesen, nichts löschen“)

Flags (Vorschau; Vertiefung Kapitel 2):

Flag	Rolle
--allow-tool=…	Tool ohne Nachfrage erlauben (z. B. 'shell(pytest)', 'write', MCP-Name)
--deny-tool=…	Tool verbieten – Vorrang vor Allow und Allow-all
--allow-all-tools	alle Tools ohne Nachfrage (hohes Risiko)
--allow-all / --yolo	alle Permissions auf einmal (Tools, Pfade, URLs – laut Doku)

# eng: viel erlaubt, rm und git push hart verboten
copilot --allow-all-tools \
  --deny-tool='shell(rm)' \
  --deny-tool='shell(git push)'

Slash-Commands in der Session (z. B. /allow-all, /yolo – aktuelle Liste: ?): erst, wenn du die Risiken von Session-Allow verstanden hast.

Kompakt zum Nachschlagen (ohne driftende Button-Labels): Anhang A.6.

---

1.7 Session steuern: Esc, Hilfe, Context

Aktion	Wie
Laufenden Schritt stoppen	Esc (während „Thinking“ / Ausführung)
Hilfe in der Session	? oder /help
Hilfe im Terminal	copilot help, copilot help permissions, …
Datei in den Prompt	@todo/store.py
Shell ohne Modell	!git status
Plan Mode	Shift+Tab (Modus wechseln) bzw. /plan
Context ansehen	/context
Context manuell komprimieren	/compact
Session fortsetzen	copilot --continue oder /resume
Agent-Arbeit rückgängig (Rewind)	/undo bzw. /rewind, oder Esc zweimal (leeres Eingabefeld)

Auto-Compact: nähert sich die Conversation ca. 95 % des Token-Limits, komprimiert die CLI die Historie im Hintergrund. Das ist kein Freibrief für endlos vage Sessions – /context zeigt, was den Fensterplatz frisst.

Steering: Während der Agent arbeitet, kannst du Folge-Nachrichten einreihen; bei abgelehnten Tools Inline-Feedback geben, statt die ganze Session zu schrotten.

Wenn der Agent daneben liegt – Rollback:

Nach einer schlechten Änderung musst du nicht alles manuell zurückbauen. Mit /undo (Alias /rewind) oder Esc zweimal (Eingabe leer) öffnest du den Rewind-Picker: zurück zu einem früheren Prompt der Session. Die CLI wählt je nach Umgebung Git-basiertes Rewind (Workspace-Snapshot) oder tools-basiertes Rewind (History, optional Dateien – teils experimentell).

Achtung: Rewind ist nicht rückgängig – spätere Session-History ist weg. Git-basiertes Rewind kann den ganzen Workspace auf den Snapshot vor dem Prompt zurücksetzen – inklusive deiner manuellen Edits und Shell-Effekte nach diesem Punkt. Nach dem Rewind: ! git status und Diff prüfen. Vertiefung: Kapitel 7.

---

1.8 Sicherheits-Basics für Tag 1

Kern: Enger Ordner, keine Secrets im Repo, Diff lesen, Deny vor YOLO.

1. CWD = Projekt, nicht Home, nicht „irgendwo in Downloads“.
2. Keine Secrets committen – Tokens nur in Env (YOUR_TOKEN als Platzhalter in Beispielen).
3. Diff lesen vor Accept/Commit; unerwartete Dateien = stoppen.
4. Session-Allow sparsam; rm und Push nie „für die Session freigeben“, nur weil der erste Aufruf harmlos wirkte.
5. YOLO (--allow-all / --yolo) nicht an Tag 1 in produktiven oder gemischten Ordnern.
6. Fremde Repos / unbekannte Skripte: erst lesen, dann Trust – oder in Cloud-Sandbox (copilot --cloud), wenn du Isolation brauchst (Preview-Hinweis in der Doku beachten).
7. Schlechte Agent-Runde: /undo / Esc×2 – aber bewusst: Rewind ist final und kann mehr als nur Agent-Edits betreffen.

Die vier Hebel aus der Einleitung greifen hier praktisch: Scope, Diff, Deny-vor-YOLO, weich/hart (Instructions kommen in Kapitel 2).

---

1.9 Häufige Fehler am ersten Tag

Problem	Was du prüfst
Auth fehlgeschlagen	Abo? Fine-grained PAT mit Copilot Requests? Classic ghp_ fälschlich genutzt? Env-Var überschreibt OAuth?
Falsche Dateien / leeres Projekt	pwd / CWD; Trusted Directory für den richtigen Ordner?
Agent schreibt trotz „nur erklären“	Prompt enger; Esc; „Ändere noch nichts.“
pytest „not found“	venv aktiv? pip install -e ".[dev]"?
beispiele/todo-cli fehlt	Nur PDF? ZIP (Begleit-Service · Material) in bekannten Ordner entpacken, Repo, oder eigenen Übungsordner; Start-Befehle: Anhang A.7
Immer wieder Permission-Prompts	normal bei Yes; Session-Allow nur bewusst; oder enge --allow-tool
Alles fühlt sich unsicher an	gut so – mit Deny und ohne YOLO starten

---

Jetzt selbst machen: Tag-1 am todo-cli

Ziel: Installation, Login, Trusted Directory und eine harmlose Session am todo-cli – ohne YOLO.

1. Installiere Copilot CLI (ein Weg aus 1.2) und prüfe copilot --version.
2. copilot login (oder /login in der Session).
3. Richte beispiele/todo-cli/ ein (venv, pip install -e ".[dev]", pytest -q – Befehlsfolge auch Anhang A.7).
4. Starte copilot in todo-cli, bestätige Trusted Directory (Session oder merken).
5. Aufgabe A: store.py erklären lassen, ohne Änderungen.
6. Aufgabe B: eine minimale Docstring- oder Kommentar-Änderung, Diff lesen, pytest -q.
7. Mindestens einmal einen Permission-Prompt mit No + kurzem Feedback ablehnen (Übung, nicht aus Prinzip).
8. Tippe ? und notiere dir drei Slash-Commands, die du morgen brauchst.

Fertig, wenn: Du kannst in eigenen Worten sagen, was Trusted Directory, Yes vs. Session-Allow und Esc bewirken – und dein Diff war so klein, dass du ihn ohne Scrollen verstanden hast.

---

Was du jetzt kannst

• Copilot CLI installieren und die Version prüfen
• interaktiv authentifizieren und Headless-Token-Regeln (fine-grained, kein ghp_) grob kennen
• Trusted Directory bewusst wählen (Session vs. merken; nicht Home)
• drei harmlose Aufgaben am todo-cli fahren
• Permission-Optionen und das Session-Allow-Risiko am rm-Beispiel erklären
• Esc, ?//help, grobes Rollback (/undo) und die Tag-1-Sicherheitsregeln anwenden

Nächste Schritte

Kapitel 2 – Grundlagen und Konfiguration: Custom Instructions (weiches Memory: .github/copilot-instructions.md, path-scoped Instructions, AGENTS.md, User-Dateien unter ~/.copilot/) gegen harte Permissions und Settings stellen – und die Faustregel „sollte nicht“ vs. „darf nicht“.

Bis dahin: lieber eine enge Session mit vielen Yes-Klicks als eine YOLO-Session, die du nicht mehr steuerst.