MarsDawn

marsdawn für Agenten

Eine Referenz für KI-Agenten und Skripte, die das Befehlszeilenwerkzeug marsdawn aufrufen. Jedes Beispiel auf dieser Seite wurde mit dem aus dem aktuellen Quellcode gebauten Werkzeug ausgeführt.

Um eine Markdown-Datei in ein PDF umzuwandeln, führe marsdawn export notes.md --json aus und lies ein JSON-Objekt von stdout. Mermaid-Diagramme und hervorgehobener Code werden genauso gerendert wie in der MarsDawn-App. export braucht die App nicht, open schon.

Was es tut

Was es nicht tut

export

marsdawn export notes.md --json

Schreibt notes.pdf neben notes.md. Optionen:

marsdawn export notes.md -o out.pdf --theme classic --paper letter --force --json

Erfolg, Exit-Code 0:

{"diagramErrors":[],"ok":true,"output":"/path/to/out.pdf","pages":1,"paper":"letter","theme":"classic"}

open

marsdawn open notes.md --json
marsdawn open notes.md:120 --json
marsdawn open notes.md --line 120 --json
marsdawn open . --json
marsdawn open notes.md --folder . --background --json

Erfolg, Exit-Code 0:

{"app":"/Applications/MarsDawn.app","ok":true,"opened":[{"line":120,"path":"/path/to/notes.md"}]}

Mit einem Ordner (marsdawn 0.5.1 und neuer), Exit-Code 0:

{"app":"/Applications/MarsDawn.app","folder":{"path":"/path/to/project","requested":true},"ok":true,"opened":[{"path":"/path/to/project/notes.md"}]}

marsdawn 0.2.x gab opened als Liste von Pfad-Strings aus. Prüfe marsdawn --version, wenn du beides verarbeiten musst.

Dateien öffnen, während Claude Code sie bearbeitet

Ein optionaler Claude Code Hook: Nachdem Claude eine Markdown-Datei geschrieben oder bearbeitet hat, öffnet er diese Datei im Hintergrund in MarsDawn, einmal pro Datei und Sitzung. Er ist aus, bis du ihn hinzufügst, Projekt für Projekt, denn ein Fenster, um das du nicht gebeten hast, kostet Aufmerksamkeit. Er führt einen Shell-Befehl aus und kostet keine Modell-Tokens.

Er braucht marsdawn 0.5.1 oder neuer, wegen --background, und die MarsDawn-App.

Sichere das als .claude/hooks/marsdawn-open.sh in deinem Projekt und mach es mit chmod +x ausführbar:

#!/bin/sh
# Claude Code PostToolUse hook: open a Markdown file Claude just wrote or edited in MarsDawn,
# in the background, once per file per session. Never blocks Claude: every path exits 0.
input=$(cat)
file=$(printf '%s' "$input" | /usr/bin/jq -r '.tool_input.file_path // empty' 2>/dev/null)
session=$(printf '%s' "$input" | /usr/bin/jq -r '.session_id // "unknown"' 2>/dev/null)

case "$file" in
  *.md|*.markdown) ;;
  *) exit 0 ;;
esac
[ -f "$file" ] || exit 0
# A hook runs with Claude Code's PATH, which may not include Homebrew's.
marsdawn=$(command -v marsdawn || { [ -x /opt/homebrew/bin/marsdawn ] && echo /opt/homebrew/bin/marsdawn; }) || exit 0
[ -n "$marsdawn" ] || exit 0

# One list per session, so a file opens once however often Claude edits it.
seen="${TMPDIR:-/tmp}/marsdawn-hook/$session"
mkdir -p "$(dirname "$seen")"
grep -qxF "$file" "$seen" 2>/dev/null && exit 0
echo "$file" >> "$seen"

"$marsdawn" open --background "$file" >/dev/null 2>&1 || true
exit 0

Füge den Hook dann zu .claude/settings.json im Projekt hinzu, oder zu .claude/settings.local.json, wenn er nur für dich gelten soll:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/marsdawn-open.sh" }
        ]
      }
    ]
  }
}

Fehler

Mit --json gibt ein Fehler ein JSON-Objekt auf stdout aus und endet mit seinem Code:

{"error":"output_exists","message":"/path/to/notes.pdf already exists. Pass --force to replace it.","ok":false}

JSON-Schemas

JSON Schema (Draft 2020-12) für jedes --json-Ergebnis:

Umgebungsvariablen

Voraussetzungen

Installieren

Mit Homebrew. Auf Apple Chips installiert es in Sekunden eine fertig gebaute Bottle, ganz ohne Xcode. Auf einem Intel-Mac kompiliert es marsdawn aus dem Quellcode, was ein paar Minuten dauert und Xcode 26 oder neuer erfordert.

brew tap redtear1115/tap && brew install marsdawn
marsdawn --version

Oder bau es aus dem Quellcode. Der erste Build lädt Abhängigkeiten und kompiliert, was ebenfalls ein paar Minuten dauert.

git clone https://github.com/redtear1115/mars-dawn-kit.git
cd mars-dawn-kit
swift build -c release --product marsdawn
.build/release/marsdawn export notes.md --json

marsdawn --version gibt die Versionsnummer aus, etwa 0.3.0, und endet mit Code 0.

Weiter