Sayknow-CLI
Programmieren sollte sich wie Denken anfühlen.
Ein fokussierter Coding-Agent-Runner für Interviews, geprüfte Pläne, tmux-native Ausführung und dauerhafte Verifizierung.
English ·
한국어 ·
中文 ·
日本語 ·
Español ·
Français ·
Deutsch
> Sayknow-CLI ist ein experimentelles Projekt im Beta-Stadium. Rechnen Sie mit Ecken und Kanten und überprüfen Sie die Ausgaben, bevor Sie sich bei wichtiger Arbeit darauf verlassen.
## Languages
Die Oberfläche ist in **7 Sprachen** lokalisiert — English, 한국어 (Koreanisch),
中文 (简体 / Vereinfachtes Chinesisch), 日本語 (Japanisch), Español (Spanisch),
Français (Französisch) und Deutsch. Beim ersten Start erkennt sie automatisch
Ihre System-Locale; wechseln Sie jederzeit unter **Settings → Appearance → Language**
oder starten Sie z. B. mit `LANG=ja_JP.UTF-8 skc`. Nicht übersetzte Zeichenketten
fallen auf Englisch zurück, und Marken-/Fachbegriffe (Claude, OpenAI, MCP, …)
bleiben in allen Locales unverändert.
## Was ist Sayknow-CLI?
Sayknow-CLI (`skc`) ist ein externes Coding-Agent-Harness. Es läuft aus dem von Ihnen gewählten Repository oder Worktree und gibt dem Agenten dann eine kleine, explizite Workflow-Oberfläche:
```text
deep-interview -> ralplan -> ultragoal
└─ optional team execution when parallel tmux workers help
```
Es ist bewusst kein verstecktes Plugin für Codex CLI, Claude Code, OpenCode oder Claw Code. Starten Sie `skc` neben diesen Tools, wenn Sie strukturierte Planung, dauerhafte Nachweise, tmux-gestützte Worker oder einen isolierten Worktree wünschen.
## Installation
```sh
npm install -g sayknow-cli # oder: bun install -g sayknow-cli
skc --version
```
Das Paket enthält vorgefertigte native Addons für macOS, Linux und Windows – keine Rust-Toolchain und kein Build-Schritt nötig. Aktualisieren: `npm install -g sayknow-cli@latest` oder `skc update` im Terminal.
> Früher aus dem Quellcode (git clone) installiert? Einmalig umsteigen: `rm -f ~/.local/bin/skc && npm install -g sayknow-cli`. Für die Installation aus dem Quellcode (Entwicklung) siehe die [englische README](../../README.md#install-from-source-development).
## Schnellstart
```sh
# Run directly in the current checkout
skc
# Use a tmux-backed leader session
skc --tmux
# Use an isolated worktree for risky or reviewable work
# --worktree takes an optional branch-like name, not a filesystem path.
skc --tmux --worktree my-task-branch
# If you already created a worktree directory, launch from that directory instead.
cd ../my-task-worktree && skc --tmux
```
Verwenden Sie innerhalb einer SKC-Sitzung die öffentliche Workflow-Oberfläche:
```text
/skill:deep-interview clarify ambiguous requirements
/skill:ralplan build and critique the implementation plan
skc ultragoal create-goals --brief-file
skc ultragoal complete-goals
```
Fügen Sie `skc team ...` nur hinzu, wenn koordinierte tmux-Worker spürbar helfen.
## Kernfunktionen
- **Interview vor dem Raten**: `deep-interview` verwandelt vage Anfragen in konkrete Anforderungen.
- **Plan vor der Veränderung**: `ralplan` prüft den Ansatz vor Codeänderungen.
- **Ausführen mit Nachweisen**: `ultragoal` verfolgt Ziele, Revisionen, Prüfungen und Abschlussnachweise.
- **Parallelisieren, wenn sinnvoll**: `team` koordiniert tmux-gestützte Worker für größere Aufgaben.
- **Extern und überprüfbar bleiben**: Laufen Sie aus einem gewählten Repo oder Worktree, ohne eine andere Agent-Runtime zu patchen.
- **Weiterarbeiten, wenn ein Provider ausfällt**: Ist das Standardmodell blockiert (keine Zugangsdaten, Kontingent erschöpft, Auth- oder Serverfehler), läuft die Sitzung mit einem Modell eines anderen Providers weiter; `/fallback` zeigt und bearbeitet diese Kette. Ein Schritt, der durch einen Neustart oder einen vorübergehenden Fehler unterbrochen wurde, wird einmal von selbst auf demselben Modell fortgesetzt. Bei Kontingentantworten wie Z.AI `1113` geht es nach einer einzigen Anfrage weiter, statt das Retry-Budget aufzubrauchen.
- **Lange Sitzungen bleiben im Kontextfenster**: Nach einer Kompaktierung startet Codex von einer frischen, für den Provider sichtbaren Basis, statt auf `context_length_exceeded` zuzuwachsen, und Kompaktierungs-Zusammenfassungen sind so formuliert, dass Provider sie nicht ablehnen.
- **Code nach Bedeutung finden**: Das Tool `locate` findet anhand einer einfachen Beschreibung, wo ein Verhalten implementiert ist, wenn Sie keinen Namen zum Greppen haben.
- **Arbeit an das richtige Modell leiten**: `/model` weist Modelle pro Rolle und pro Einsatzzweck im Detail zu; Subagent-Aufgaben deklarieren eine `specialty`, damit sie auf dem Modell landen, das Sie für diese Art von Arbeit gewählt haben.
- **Direkt aus der Sitzung ausliefern**: Die Tools `github` und `gitlab` öffnen und prüfen Pull-/Merge-Requests und CI, ohne SKC zu verlassen.
- **Belegen, dass die Tests auf diesem Code liefen**: Das Plugin `verification-receipts` speichert zu jedem Testlauf einen Beleg und meldet, wenn sich der Code seitdem geändert hat.
- **Zu jeder Sitzung zurückkehren**: `alt+r` öffnet die Fortsetzen-Auswahl, `ctrl+q` setzt die letzte Sitzung fort, dazu `/star`, `/fork`, `/rename` und `/import-session` für Codex- und Claude-Code-Transkripte.
## Workflow-Oberfläche
Sayknow-CLI liefert vier Standard-Workflow-Skills:
| Skill | Was es tut |
| ---------------- | --------------------------------------------------------------------- |
| `deep-interview` | Klärt mehrdeutige Anforderungen vor Planung oder Codeänderungen. |
| `ralplan` | Erstellt und kritisiert einen Implementierungsplan vor der Veränderung. |
| `ultragoal` | Verfolgt Ziele durch Ausführung, Revision, Verifizierung und Nachweise. |
| `team` | Koordiniert tmux-gestützte Worker, wenn parallele Ausführung sich lohnt. |
Und vier mitgelieferte Rollen-Agenten:
| Agent | Was es tut |
| ----------- | -------------------------------------------------- |
| `executor` | Begrenzte Implementierung, Fixes und Refactorings. |
| `architect` | Schreibgeschützte Architektur- und Code-Review-Bewertung. |
| `planner` | Schreibgeschützte Sequenzierung und Abnahmekriterien. |
| `critic` | Schreibgeschützte Plan-Kritik und Umsetzbarkeitsprüfung. |
Kein wucherndes Standard-Skill-Zoo: SKC verbessert sich, indem es diese kleine Methode besser macht.
## Integrierte Tools
Der Agent arbeitet mit diesen Tools. Als *opt-in* markierte Tools bleiben deaktiviert, bis Sie sie unter **Settings → Tools** (oder über den angegebenen Schlüssel in `~/.skc/config.yml`) aktivieren.
| Bereich | Tools |
| ---- | ----- |
| Dateien und Code | `read`, `write`, `edit`, `find`, `search`, `locate` (Code per Beschreibung finden), `ast_grep` / `ast_edit` (syntaxbewusstes Suchen und Umschreiben), `lsp` |
| Shell und Laufzeit | `bash`, `eval` (JS-/Python-Zellen), `ssh`, `debug`, `bisect`, `calc` |
| Delegation und Tracking | `task` (Subagents), `subagent`, `job`, `monitor`, `cron`, `irc` (mit laufenden Agenten sprechen), `todo_write`, `goal`, `checkpoint` / `rewind` |
| Git-Hosting | `github` (*opt-in*, `github.enabled`): Pull Requests, Pushes, CI-Läufe über `gh` · `gitlab` (*opt-in*, `gitlab.enabled`, benötigt [`glab`](https://gitlab.com/gitlab-org/cli)): `mr_create` (liefert den bereits offenen MR statt eines Duplikats), `mr_view`, `mr_list`, `ci_status` für gitlab.com und selbst gehostete Instanzen |
| Web und Geräte | `web_search`, `browser`, `computer`, `render_mermaid` |
| Discovery | `search_tool_bm25` (aktiviert versteckte und MCP-Tools bei Bedarf), `skill`, `skill_discovery`, `ask` |
Mit `--tools read,bash,...` wählen Sie das Tool-Set für einen einzelnen Lauf; auch Plugin-, benutzerdefinierte und MCP-Toolnamen werden dort akzeptiert.
## Plugins
SKC lädt Plugin-Bundles (Tools, Hooks, Skills, MCP-Server), deren Hashes bei der Installation geprüft werden und die in Quarantäne kommen, wenn sich danach eine Datei ändert. Verwaltet werden sie mit `skc plugin install|list|...`.
**`verification-receipts`** (in diesem Repository enthalten) beantwortet die Frage „Haben die Tests auf dem Code, der jetzt da ist, tatsächlich bestanden?“:
- `verification_run` führt explizit angegebene Testdateien mit `bun test` oder `node --test` aus und speichert einen unveränderlichen Beleg: Bestanden-/Fehlgeschlagen-Zahlen pro Datei plus einen Fingerabdruck des Arbeitsverzeichnisses.
- `verification_status` berechnet diesen Fingerabdruck neu, ohne die Tests erneut auszuführen, und meldet `fresh` oder, sobald sich der Code geändert hat, `stale`.
- `verification_loop` und seine Hooks erinnern Sie, wenn ein `task` im Hintergrund ohne aktuellen Beleg beendet wurde.
Es dient nur als Hinweis, läuft nur unter POSIX und benötigt Node 24.11.1+ für `node --test`. Es ist nicht Teil des npm-Pakets; installieren Sie es aus einem Checkout:
```sh
git clone https://github.com/jaybeyond/Sayknow_CLI.git
skc plugin install ./Sayknow_CLI/packages/coding-agent/bundles/verification-receipts --user
```
## Funktioniert neben Ihrem bestehenden Agenten oder Bot
| Tool oder Bot | Empfohlener SKC-Befehl | Grenze |
| ----------- | ----------------------- | -------- |
| Codex CLI | `skc --tmux --worktree ` oder `skc` | `--worktree` benennt einen SKC-verwalteten Geschwister-Worktree; für einen bestehenden Pfad wechseln Sie zuerst mit `cd` dorthin. |
| Claude Code | `skc --tmux` oder `skc --tmux --worktree ` | SKC wird keine Claude-Code-Erweiterung. |
| OpenCode | `skc` oder `skc --tmux` | Heute nur External-Runner-Workflow. |
| Claw Code | `skc --tmux --worktree ` | SKC installiert sich nicht in Claw Code und ersetzt es nicht. |
| Externer Controller / Bot | `skc mcp-serve coordinator` plus `skc setup hermes` für kompatible Konfiguration oder `skc --mode rpc` für einen Subprozess-Worker | Jeder MCP-/RPC-fähige Bot steuert SKC über den generischen Coordinator-/RPC-Vertrag, nicht durch Scrollback-Scraping. |
Für generisches Drittanbieter-Bot-Setup und anbieterunabhängige Smokes siehe [`docs/bot-integration.md`](docs/bot-integration.md). Für die Reife-Klassifizierung über MCP-, RPC-, ACP- und Bridge/HTTPS-Oberflächen siehe [`docs/external-control-readiness.md`](docs/external-control-readiness.md). Für tiefergehende Protokolldetails siehe [`docs/hermes-mcp-bridge.md`](docs/hermes-mcp-bridge.md), [`docs/rpc.md`](docs/rpc.md) und [`docs/bridge.md`](docs/bridge.md). Für die Roadmap der Remote-Operator-Oberflächen siehe [`docs/sayknow-remote.md`](docs/sayknow-remote.md) (Web-Steuerrad) und [`docs/telegram-remote.md`](docs/telegram-remote.md) (Telegram-Lifecycle-Button).
## Konfiguration
Retry-, Resume- und Fallback-Verhalten der Provider liegt in `~/.skc/config.yml` (die Werte unten sind die Standardwerte):
```yaml
retry:
requestMaxRetries: 4
streamMaxRetries: 100
maxRetries: 3
maxDelayMs: 300000
autoResume: true # einen unterbrochenen Schritt einmal fortsetzen, auf demselben Modell
maxSilentTimeouts: 3 # nach so vielen Timeouts ohne Ausgabe abbrechen
fallback:
auto: true # bei blockiertem Standardmodell mit einem anderen angemeldeten Provider weitermachen
maxAttempts: 3 # Versuche pro Modell der Kette, bevor zum nächsten gewechselt wird
```
`requestMaxRetries` gilt, bevor ein Stream aufgebaut wird. `streamMaxRetries` gilt nur für replay-sichere, vorübergehende Stream-Fehler. Ungültige Authentifizierung, nicht unterstützte Modelle/Provider, fehlerhafte Requests, Kontextüberlauf, Benutzerabbrüche und dauerhafte Kontingentfehler schlagen auf dem aktuellen Modell sofort fehl; mit `fallback.auto` übergibt ein blockiertes Standardmodell dann an das nächste Modell der Kette (`/fallback` zeigt und bearbeitet sie).
## TUI-Identität
Die Standard-TUI-Identität ist das SKC-**ink-octopus**-Theme — Oktopus-Tinte: warmer Graphit, papierfarbener Text, ein Bernstein-Akzent — für dunkle Terminals, mit **blue-octopus** für helle Terminals. Eine warme **red-octopus**-Variante ist ebenfalls dabei für alle, die eine dunklere, kontrastreiche Palette bevorzugen. Drei zusätzliche Migrations-Themes — `claude-code`, `codex` und `opencode` — spiegeln das Aussehen dieser Tools für einen einfachen Augen-Umstieg wider und sind über Settings oder `/theme` auswählbar. Explizite Benutzer-Theme-Einstellungen gewinnen weiterhin.
### Raster der mitgelieferten Themes
Wählen Sie über Settings (`Appearance -> Dark theme` / `Light theme`) oder `/theme`.
| Theme | Visueller Eindruck | Beste Eignung |
| --- | --- | --- |
| `blue-octopus` | Blaue Oktopus-Palette mit tentakelblauen Akzenten. | Standard für helle Terminals. |
| `red-octopus` | Warme rote Oktopus-Variante mit starkem Status-Kontrast. | Kontrastreiche dunkle Alternative. |
| `ink-octopus` | Oktopus-Tinte — warmer Graphit-Hintergrund, papierfarbener Text, ein einziger Bernstein-Akzent. | Standard für dunkle Terminals. |
| `glow-octopus` | Tiefsee-Biolumineszenz — Petrol-Schwarz mit leuchtendem Grün und Violett als Zweitfarbe. | Dunkle Terminals mit kräftigem Akzent. |
| `violet-octopus` | Pflaumendunkel mit Lavendel-Akzenten und Aprikose als Zweitfarbe. | Weiche, farbige dunkle Alternative. |
| `claude-code` | Von Claude Code inspirierte dunkle Palette mit terrakotta- und pinkfarbenen Highlights. | Claude-Code-Muskelgedächtnis, ohne SKC zu verlassen. |
| `codex` | Klare dunkle blaugraue Palette mit schärferem Coding-Session-Kontrast. | Ein Codex-ähnlicher dunkler Arbeitsbereich. |
| `opencode` | Von OpenCode inspirierte dunkle Palette mit kräftigeren Terminal-Akzenten. | OpenCode-Muskelgedächtnis im mitgelieferten Picker. |
## Entwicklung
Abhängigkeiten installieren, native Bindings bauen und lokale Standardwerte einrichten:
```sh
bun install
bun run build:native
bun run install:defaults
```
Die `.node`-Binärdatei für `@sayknow-cli/natives` ist gitignored und vor jeder CLI-Ausführung erforderlich (`install:defaults`, `dev:link`, Tests).
### Kanonisch: Entwickler-`skc` bauen und verlinken
Damit der globale Befehl `skc` **den TypeScript-Quellcode dieses Checkouts** ausführt (live bei jeder Bearbeitung, mit funktionierenden Skills/Natives), verlinken Sie ihn in Ihren `PATH`:
```sh
bun install
bun run dev:link
```
`dev:link` legt einen Symlink `skc` → `packages/coding-agent/src/cli.ts` nach `~/.local/bin` an (überschreibbar mit `SKC_DEV_LINK_DIR`), ersetzt dieses verwaltete Ziel, warnt und schlägt fehl, falls ein anderes `skc` es weiter vorne im `PATH` überschattet, und führt `--smoke-test` aus, um zu bestätigen, dass `@sayknow-cli/natives` geladen wird. Verwenden Sie `bun run install:dev` für das vollständige Bootstrap (Installation + Link + `setup defaults`).
Prüfen Sie jederzeit, ob Ihr `skc` abgedriftet ist (falsche Quelle oder eine kompilierte Binärdatei, die keine Skills laden kann):
```sh
bun run dev:doctor
```
> Verwenden Sie für die tägliche Entwicklung **nicht** die kompilierte Binärdatei. `bun --cwd=packages/coding-agent run build` erzeugt ein eigenständiges `dist/skc`, aber eine mit `bun build --compile` erstellte Binärdatei kann `@sayknow-cli/natives` nicht dynamisch laden, sodass Skills mit `Cannot find module '@sayknow-cli/natives' from '/$bunfs/root/skc'` fehlschlagen. Die Ausführung aus dem Quellcode über `dev:link` vermeidet dies. Bauen Sie die Binärdatei nur, wenn Sie ein Release validieren.
Führen Sie die CLI direkt aus dem Quellcode ohne Verlinkung aus:
```sh
bun packages/coding-agent/src/cli.ts --help
```
Standard-Workflow-Definitionen liegen im Quellcode, nicht in committeten `.skc`-Kopien:
```text
packages/coding-agent/src/defaults/skc/skills//SKILL.md
packages/coding-agent/src/prompts/agents/.md
```
Für Änderungen an Workflow-Definitionen oder Rebrand-Oberflächen führen Sie die Projekt-Gates aus:
```sh
bun scripts/check-visible-definitions.ts
bun scripts/verify-g002-gates.ts
bun scripts/rebrand-inventory.ts --strict
bun test packages/coding-agent/test/default-skc-definitions.test.ts
```
Für eine Paket-für-Paket-Übersicht siehe [`docs/codebase-overview.md`](docs/codebase-overview.md).
## Mitwirkende
Beiträge, Fehlerberichte und Release-Validierung sind über GitHub Issues und Pull Requests willkommen.
## Inspirationen und Herkunft
Die Standard-TUI-Identität von Sayknow-CLI ist die Oktopus-Familie: ink-octopus als dunkler Standard, blue-octopus als heller Standard sowie red-octopus, glow-octopus und violet-octopus als Alternativen. Es liefert außerdem die Migrations-Themes `claude-code`, `codex` und `opencode`, deren Paletten von diesen Tools inspiriert sind, damit Benutzer, die von ihnen wechseln, einen vertrauten Look erhalten. Es baut auf Erkenntnissen aus einer kleinen Familie von Agent-Harnesses auf und hält die öffentliche SKC-Oberfläche bewusst fokussiert. Die historische Zuordnung wird in [`NOTICE.md`](NOTICE.md) geführt.
## Lizenz
MIT. Siehe [`LICENSE`](LICENSE).