MarsDawn

AI エージェント向け marsdawn

marsdawn コマンドラインツールを呼び出す AI エージェントとスクリプトのためのリファレンスです。このページのすべての例は、現在のソースからビルドしたツールに対して実際に実行したものです。

Markdown ファイルを PDF に変換するには、marsdawn export notes.md --json を実行し、stdout から1つの JSON オブジェクトを読み取ってください。Mermaid 図とハイライトされたコードは、MarsDawn アプリと同じ方法でレンダリングされます。export にアプリは不要ですが、open には必要です。

できること

できないこと

export

marsdawn export notes.md --json

notes.pdf を notes.md の隣に書き出します。オプション：

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

成功、終了コード 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

成功、終了コード 0：

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

フォルダを指定した場合（marsdawn 0.5.1 以降）、終了コード 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 では opened はパス文字列のリストでした。両方を扱う必要がある場合は marsdawn --version を確認してください。

Claude Code が編集したファイルを開く

オプトインの Claude Code フックです。Claude が Markdown ファイルを書き込んだり編集したりすると、そのファイルを MarsDawn でバックグラウンドで開きます。開くのはセッションごと、ファイルごとに一度だけです。頼んでいないウインドウは注意をそらすので、追加しない限り有効にならず、プロジェクトごとに追加します。シェルコマンドを実行するだけなので、モデルのトークンは使いません。

--background のために marsdawn 0.5.1 以降と、MarsDawn アプリが必要です。

次の内容をプロジェクトの .claude/hooks/marsdawn-open.sh として保存し、chmod +x で実行可能にします。

#!/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

次に、プロジェクトの .claude/settings.json にフックを追加します。自分だけで使う場合は .claude/settings.local.json に追加します。

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

失敗時

--json を指定すると、失敗時は stdout に1つの JSON オブジェクトを出力し、対応するコードで終了します。

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

JSON Schema

各 --json 結果に対応する JSON Schema（draft 2020-12）：

環境変数

必要環境

インストール

Homebrew を使う場合。Apple シリコンでは、Xcode 不要でビルド済みのボトルを数秒でインストールします。Intel Mac では marsdawn をソースからコンパイルするため数分かかり、Xcode 26 以降が必要です。

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

または、ソースからビルドします。最初のビルドでは依存関係の取得とコンパイルが行われ、これも数分かかります。

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 は 0.3.0 のようなバージョン番号を表示し、コード 0 で終了します。

次に