From 924960476ecd19009774be09d788344f4e672937 Mon Sep 17 00:00:00 2001 From: Tim Otlik Date: Sun, 8 Feb 2026 11:09:35 +0100 Subject: [PATCH] init --- AGENTS.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 107 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 235 insertions(+) create mode 100644 AGENTS.md create mode 100644 README.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..bef8d9f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,128 @@ +# Agent Guidelines für ZellIDE + +## Projekt-Kontext + +ZellIDE ist eine Terminal-basierte IDE-Umgebung für Tim, einen erfahrenen Software-Entwickler der von VSCode zurück ins Terminal möchte. Das Projekt kombiniert Zellij (Terminal-Multiplexer), Helix (Editor), Yazi (File-Manager) und lazygit zu einer integrierten Entwicklungsumgebung. + +## Lern- und Arbeits-Stil + +**Tim lernt am besten durch:** +- Schrittweises Erweitern von Code-Snippets +- Konkrete Beispiele vor Theorie +- Mini-Challenges zum Festigen +- Learning by doing, nicht durch dicke Dokumentation + +**Wichtig beim Entwickeln:** +- Pragmatische Lösungen vor komplexen Architekturen +- Ein Feature nach dem anderen +- Testen in echten Use-Cases (z.B. infrastructure-Repo) +- Keine Überladung mit zu vielen Optionen auf einmal + +## Technische Anforderungen + +### Umgebung +- **OS:** Linux (primär), auch für Remote-Server +- **Shell:** Zsh +- **Package Manager:** System-native (dnf, apt) + uv für Python +- **VPN:** Tailscale für Server-Zugriff +- **Git:** Forgejo auf zeus.turkey-court.ts.net + +### Bestehende Infrastruktur +- Mehrere Server: Zeus (Hetzner), Hephaistos, BigSister (Synology), rom-master-5000 (RPi5) +- Aktuell: tmux auf allen Servern (soll zu Zellij migriert werden) +- Linear für Projekt-Management +- Git-basierte Workflows + +### Ziel-Setup +- Lokale Entwicklung: ZellIDE mit vollem Feature-Set +- Remote-Server: Gleiche ZellIDE-Umgebung für Konsistenz +- Keine nested Sessions (Zellij in Zellij vermeiden) + +## Code-Richtlinien + +### Scripting +- **Shell-Scripts:** Bash (für Kompatibilität) oder Zsh (wenn zsh-spezifische Features genutzt werden) +- **Kommentare:** Auf Deutsch, Code-Variablen auf Englisch +- **Fehlerbehandlung:** Immer explizit prüfen, keine stillen Failures +- **Debugging:** Tim nutzt custom outputs statt Debugger + +### Konfigurationsdateien +- **Format:** KDL für Zellij, TOML für Helix +- **Dokumentation:** Inline-Kommentare für nicht-offensichtliche Optionen +- **Pfade:** Absolute Pfade vermeiden, ~/ nutzen wo möglich + +### Git-Workflow +- **Branches:** Main für stabile Features, Feature-Branches für Entwicklung +- **Commits:** Aussagekräftige Messages auf Deutsch +- **Remote:** zeus.turkey-court.ts.net/totlik/zellide.git + +## Kommunikations-Präferenzen + +**Bevorzugt:** +- Du-Form (nicht formal) +- Rückfragen stellen bei Unklarheiten +- Schritt-für-Schritt-Erklärungen +- Konkrete Code-Beispiele + +**Vermeiden:** +- Zu viele Optionen gleichzeitig präsentieren +- Theoretische Abhandlungen ohne Code +- Annehmen was Tim will - lieber nachfragen +- Überspringen von Zwischen-Schritten + +## Testing & Iteration + +### Test-Projekte +- **Primär:** ~/git/infrastructure (Ansible, Docker-Compose, Configs) +- **Später:** Rust-Projekte nach erfolgreicher IDE-Migration + +### Iterativer Prozess +1. Kleine, testbare Einheit entwickeln +2. Mit echtem Use-Case testen +3. Feedback einholen +4. Anpassen und erweitern +5. Erst dann zum nächsten Feature + +### Erfolgs-Kriterien +- Fühlt sich flüssig an wie VSCode +- Keine nervigen Edge-Cases im täglichen Workflow +- Gleiche Erfahrung lokal und remote +- Tim kann seine Muscle-Memory aufbauen + +## Besondere Hinweise + +### Helix vs Vim +- Tim kommt von Vim-Bindings +- Helix verwendet selection-first statt verb-noun +- Geduld in der Umgewöhnungsphase +- Keybind-Referenzen bereitstellen + +### Session-Management +- Session-Namen sind wichtig für Übersicht +- Präfix-System konsequent nutzen +- Keine Session-Verschachtelung +- Auto-Cleanup von alten Sessions ist nice-to-have, nicht kritisch + +### Erweiterbarkeit +- System soll wachsen können +- Heute IDE, morgen vielleicht Monitor-Dashboards +- Prefix-System ermöglicht einfache Erweiterung +- Nicht zu früh über-engineeren + +## Nächste Milestones + +1. **Phase 1:** Basis-Setup (Zsh-Hooks, Detection, Helper-Scripts) +2. **Phase 2:** Zellij-Layout + Helix-Config für bestehende Sprachen +3. **Phase 3:** Testing mit infrastructure-Repo +4. **Phase 4:** Server-Migration vorbereiten +5. **Phase 5:** Rust-Umgebung einrichten + +## Fragen bei Unsicherheit + +Bevor du Code schreibst oder Entscheidungen triffst: +- Ist das die einfachste Lösung? +- Braucht Tim das wirklich jetzt? +- Passt es zum iterativen Ansatz? +- Hast du alle Informationen oder solltest du nachfragen? + +**Im Zweifel: Nachfragen!** Tim gibt lieber klares Feedback als dass er später umbauen muss. diff --git a/README.md b/README.md new file mode 100644 index 0000000..77368aa --- /dev/null +++ b/README.md @@ -0,0 +1,107 @@ +# ZellIDE + +Eine Terminal-basierte IDE-Umgebung gebaut auf Zellij, Helix, Yazi und lazygit. + +## Vision + +Weg von VSCode, zurück ins Terminal - aber mit modernem Komfort. Eine IDE-Erfahrung die sich anfühlt wie eine richtige IDE, aber komplett im Terminal läuft und keine Electron-Bloat mitbringt. + +## Kernideen + +### Auto-Detection & Session Management + +**Git-basierte Projekterkennung:** +- Beim `cd` in ein Git-Repository wird automatisch erkannt ob es ein IDE-Projekt ist +- Session-Namen werden vom Git-Root-Namen abgeleitet +- Format: `ide:projektname` +- Eine `.zellij-ide` Datei im Git-Root markiert das Projekt + +**Intelligentes Session-Handling:** +- Beim Betreten eines Projekts: Angebot die IDE zu starten oder zu einer laufenden Session zu attachen +- Kein Nesting: Wenn bereits in einer Zellij-Session, kein erneuter Prompt +- Manuelles Attachen jederzeit möglich via Helper-Script + +### Session-Naming-Schema + +Verschiedene Session-Typen für verschiedene Use-Cases: + +**IDE Sessions:** `ide:projektname` +- Immer für Git-Projekte +- Name vom Repository-Root abgeleitet +- Persistente Layout-Konfiguration + +**Shell Sessions:** `zsh:fancy-name` oder `zsh:verzeichnisname` +- Fancy-Names: Zufällige Kombinationen wie "super-koala", "elegant-mammoth" +- Oder: Aktuelles Verzeichnis als Name +- Für ad-hoc Terminal-Arbeit + +**Custom Sessions:** Offen für weitere Typen +- Prefix-System ermöglicht Erweiterung +- z.B. `debug:`, `monitor:`, etc. + +### Layout-Struktur + +**Haupt-Layout für IDE:** +``` +┌─────────────┬──────────────────────────┐ +│ yazi │ │ +│ (file tree) │ helix │ +│ │ (main editor) │ +│ │ │ +├─────────────┤ │ +│ lazygit │ │ +│ │ │ +└─────────────┴──────────────────────────┘ +``` + +**Floating Pane:** +- Ad-hoc Terminal via Keybind (z.B. Ctrl+t) +- Für schnelle Befehle ohne Layout zu zerstören +- Ansible-Playbooks ausführen, docker-compose up, etc. + +### Integration & Features + +**Helix LSP Support:** +- YAML (ansible-language-server) +- Docker Compose +- TOML/JSON für Configs +- Bash/Shell Scripts +- Später: Rust (rust-analyzer) + +**Git-Integration:** +- Inline Git-Gutter in Helix +- lazygit für visuelle Git-Operationen +- Beide Tools arbeiten auf dem gleichen Repo + +**File Navigation:** +- yazi als File-Explorer mit Previews +- Helix fuzzy file finder (Space+f) +- Buffer-Switcher (Space+b) + +## Workflow-Beispiel + +1. `cd ~/git/infrastructure` +2. Prompt: "IDE für 'infrastructure' starten? [y/N]" +3. Bei 'y': Zellij startet mit IDE-Layout, Session `ide:infrastructure` +4. Bei 'n': Normale Shell, später `ide-attach` zum Starten +5. Arbeit in der IDE: yazi für Navigation, helix zum Editieren, lazygit für Commits +6. Floating Terminal (Ctrl+t) für ansible-playbook Ausführung +7. Detach jederzeit, Re-Attach von überall im Projekt + +## Ziele + +- **Komfort:** Fühlt sich an wie eine richtige IDE +- **Performance:** Kein Electron, native Terminal-Tools +- **Flexibilität:** Erweiterbar, anpassbar, scriptbar +- **Konsistenz:** Gleiche Umgebung lokal und auf Remote-Servern +- **Muscle Memory:** Helix-Keybinds lernen und überall nutzen + +## Nächste Schritte + +1. Basis-Setup: Zsh-Hooks, Session-Detection +2. Zellij-Layout definieren +3. Helix-Konfiguration mit LSP +4. Helper-Scripts für Session-Management +5. Testing mit infrastructure-Repo +6. Migration von tmux auf Servern +7. Rust-Entwicklungsumgebung aufsetzen