katra

katra

コミットとともに記録する、リッチコンポーネント対応の開発ログです。ソロで開発する場合も、コーディングエージェントと一緒に開発する場合も、仕様駆動のエージェント開発を支える記憶になります。インタラクティブなコンポーネントを埋め込んだ Markdown エントリーには、説明対象のコミットと diffstat が自動で記録され、ライブで自動再読み込みされるページとして表示されます。

ひとつのワークフローを確実に実行するために作られました。作業の背景、行き詰まった点、スクリーンショットやアニメーションなどを、作業と同時に記録し、スキップされがちな「昇格」ステップのせいで下書きを失わないことです。

同じストアが、セッションをまたいでもエージェントの有効性を保ちます。設計はコミット済みの仕様として保存され、タスクはそれらを参照します。新しいセッションでは、もう存在しない会話から意図を再導出するのではなく、仕様を読んで作業を始めます。この流れについては、以下のエージェントのワークフローで説明します。

katra init --install-hook        # store + portable Git auto-stamp
katra new "Reworked the swing"   # start a draft (a markdown file)
katra capture shot.png           # drop a screenshot into it
katra compare before.png after.png
katra serve                      # live page on the LAN, reloads as you write
git commit -m "…"                # the draft is stamped with this commit

ひとつのアイデア

下書きとは、コミットハッシュのないエントリーです。 状態遷移はこれだけです。

作成した瞬間に In Progress パネルに表示されます。スクラッチファイルも、別のドキュメントも、「公開」切り替えもありません。ハッシュと diffstat を追加して記録することで、ログに反映されます。

それ以外のすべては、ここから導かれます。昇格させるのを忘れたバッファに何かが取り残されることはありません。そもそもバッファがないからです。ログは実際に作業した順に並び、うまくいかなかった部分も含まれます。圧縮された履歴では、いつも失われてしまう部分です。

ビューアー

katra serve はストアをライブページとして表示します。ビルド工程はなく、執筆中に静的サイトを再生成する必要もありません。中央の流れは、起きた順に並ぶログです。未来のエピック、現在進行中のエントリー、そして過去の順です。右側のレールには、単なるファイル一覧では埋もれてしまう情報が表示されます。今も重要な決定や、一連の作業に関わるタグです。

スクリーンショットをさらに表示

開いたエントリー。このエントリーは下書きの途中で公開されており、katra compare で取り込んだ、2 種類のアイコンマークの方向性を比較するビフォー・アフタースライダーが表示されています。

ステータス別にグループ化されたボード。specced は todo と doing の間に独立した列として表示されます。設計が確定しているものの、まだ誰も実装していないタスク用です。

ハブ。マシンに登録されているすべてのプロジェクトを 1 ページに表示します。これはメンテナー自身のもので、14 個のプロジェクトと 25 件の進行中の項目があり、どこにも再入力されていません。

問題

大変な 1 週間を終えます。コミットには fix streaming、wip、actually fix streaming と書かれています。半年後、スポーン予算がなぜ最近接優先なのか知る必要があっても、その答えは差分にはありません。頭の中にあり、もう手元にないスクリーンショットにも残っていたのです。

よくある解決策はどれも、同じ理由でうまくいきません。もう 1 つの仕事になってしまうからです。

• CHANGELOG.md に記録されるのはリリースされた内容であり、学んだことではありません。説明しようとしている差分をもとに、リリース時に書かれます。
• Wiki や Notion のページはリポジトリにないため、すぐにコードとの食い違いが生じ、誰かがクローンしても見つかりません。
• ブログ記事はあとから記憶を頼りに書かれます。まさにそのとき、必要だった細部は失われています。
• Conventional Commits では、機械で読み取れる「何を」は得られても、「なぜ」や画像、却下した代替案を書く余地はありません。

共通する問題は、どれも作業のあとに行う手順だということです。そして作業のあとに回す手順は、作業が長引くと省かれてしまいます。まさに、ログの価値が最も高くなるときにです。

katra が目指すのは、ログを作業後に行うタスクではなく、作業に伴って自然に生じるものにすることです。作業を始めるときに下書きを作成し、進めながらスクリーンショットや考えを蓄積します。そして、いずれ行う予定だったコミットによって、それが公開されます。

エージェントのワークフロー

これが katra の中核であり、静的サイトジェネレーターと比べて独特な形をしている理由です。エージェントのセッション間で失われないようにするものが二つあるからです。エージェントが作業の基準にする設計と、実際のビルドがどのように進んだかの記録です。

最後にログを残すエージェントは、差分の要約を書きます。しかし、それは差分を見れば分かることです。失われるのは最終状態に至るまでのすべて、つまり失敗したアプローチ、計画を変えるきっかけになった測定値、バグの様子です。そこで katra は、作業の「中に」ログを組み込みます。共通の手順は「Katra のワークフロー」にある CLI の一連の操作です。エピックやタスクを宣言し、必要に応じてコミット済みの仕様を添付して読み、実装前にドラフトを開き、作業を進めながら判断と根拠を記録し、最後にスタンプを付けて閉じます。Codex、Claude Code、MCP、または通常のシェルから利用できます。

katra init --install-hook

これにより Katra が作成され、ハーネスに依存しない Git の post-commit 自動スタンプがインストールされます。Claude Code ユーザーは、追加で katra setup を実行すると、スキルと7つのセッションフックをインストールできます。このオプションのアダプターを使うと、次のようになります。

1. SessionStart は、アクティブなドラフト、未解決のメモリ、または調整が必要な進行中の変更を報告します。
2. PostToolUse は、エージェントが編集したすべてのファイルを記録します。
3. Stop は、作成したコードに変更があり、その目的が何も宣言されていない場合、ターンの終了をブロックします。
4. PreToolUse は、ステージ済みコードに調整記録がない git commit をブロックします。
5. コミットすると post-commit フックが実行され、ドラフトにスタンプが付きます。

このゲートは利用者の反応が大きい機能なので、作動する条件を正確に説明しておく価値があります。ターン中に作成したコードが作業ツリーに残っており、katra ディレクトリの外にあり、その目的が何も宣言されていない場合にのみブロックします。会話だけのターンはブロックされません。編集してから元に戻した場合、差分がなければブロックされません。他の人が以前から残していた変更はあなたの作業ではないため、ブロックされません。同じ変更がそのまま残っている場合、ブロックされたターンが再度ブロックされることはありません。

ゲートを通過するには、<task> に katra task list で確認できるスラッグを指定します（または katra task new で作成します）。

katra reconcile --advance <task>   # this moves a task forward
katra reconcile --close   <task>   # this finishes one
katra reconcile --no-task --reason "…"
katra reconcile status             # what does the gate want right now?

katra を試している場合は、katra setup --no-gate を使用してください。 コミットをブロックすることなく、通知と自動スタンプを利用できます。後から katra setup を再実行すれば、ゲートを有効にできます。すべてのリポジトリにブロックするフックを導入することは、コミット時の操作感を大きく変えるため、意図的に選択するべきです。

シェルコマンドではなくツールの呼び出しを希望するクライアント向けに、MCP サーバー（katra-mcp）もあります。15個のツールで、エントリーに加えてタスク、タスク仕様、エピック、判断、記事を扱えます。詳しくは「Katra のワークフロー」と「エージェント」を参照してください。

最初のリリースが公開されると、公式 MCP Registry から、OCI パッケージを通じて同じ stdio サーバーを検出できるようになります。そのイメージには katra-mcp と git だけが含まれています。これは、コンテナーのほうが Katra の利用に適しているからではなく、レジストリがインストール可能なパッケージを必要とするためです。レジストリクライアントから使う場合も、リポジトリの作業ツリーを公開する必要があります。直接利用する場合は、上記のネイティブバイナリーをインストールしてください。

仕様駆動であり、仕様から派生するものではありません

現行ソースの機能: インストール済みの v0.1.0 CLI には、まだ task spec、task new --spec、および specced というリストフィルターのヘルプ値はありません。 次のリリースまでは、このフェーズ用に make all で現行ソースをビルドしてください。 リリースチェックリストでは、パッケージ化されたバイナリに対してこれら3つすべてを検証するようになりました。

タスクには spec: を付けられます。これは katra 内のノードスラッグ（判断、記事、エントリー）またはリポジトリのルートからの相対パスで、[[wikilink]] と同じ方法で解決されます。katra task spec <slug> <ref> でこれを関連付けると、タスクは todo（または空）から新しいステータス specced に移ります。これは、設計が存在し、コミット済みで、まだ誰も構築に着手していない状態です。

katra task new "Cache swap"                           # todo, slug: cache-swap
katra decide "Cache invalidation: TTL, not events"   # write the design
katra task spec cache-swap cache-invalidation-ttl-not-events   # by node slug
katra task start cache-swap                          # -> doing, implement from it

利点は実装効率の向上であり、セッションをまたいで効果が積み重なります。初めて作業に取り組むエージェントは、新しいコンテキストウィンドウや別の日からでも、もう存在しない会話から意図を再導出する代わりに仕様を読みます。katra task list --status specced が作業リストです。仕様は必須ではありません。todo → doing への移行も引き続き可能で、ほとんどのタスクには仕様は必要ありません。specced は、「これをやるべきだ」と「誰かが取り組んでいる」の間に置かれるステータスにすぎません。まず設計を書き留めておく価値があるタスクに使います。また、実装中に書くエントリーは記録のもう半分になります。仕様で提案した内容と、実際に起きたことを、行き止まりも含めて記録します。

Claude Code のメモリを任意で取り込む

Claude Code はプロジェクトごとのネイティブメモリを保持します。katra はこれをプライベートな台帳に取り込めるため、誰も書き直さなくてもログに作業の詳細が記録されます。デフォルトで取り込まれるのは metadata.type: project のメモリのみです。user（あなたがどんな人か）や feedback（どのように作業してほしいか）は取り込みません。どちらもコミットするログには適さないためです。シークレット検出器に一致するものや、sensitiveTerms に指定した用語を含むものは、提示されずに隔離されます。

台帳そのものは katra/.state/memory-ledger.json にあり、意図的にローカルに置かれ、gitignore されています。エージェントの生のメモリは、あなたやあなたのマシンに関する未確認のテキストであり、デフォルトでは共有ブランチに決して到達させるべきではありません。そこからあなたが選んで書き起こした文章だけが共有されます。そのため「確認」とは、生成したマシン上で katra memory scan | status | resolve | ignore キューを確認することを意味します。リポジトリをクローンしたチームメイトが受け取るのはあなたのエントリーであり、あなたの台帳ではありません。

代替ツール

導入する前にお読みください。一部の機能を担うツールはいくつかあり、その中にはこちらより適しているものもあります。

ツール	代わりに使う場合
Keep a Changelog + release-please	ユーザー向けに、リリースで何を公開したかの記録を残したい場合。これはなぜそうしたかを記録する作業用の文書とは別物で、ほとんどのプロジェクトでは両方用意するべきです。
adr-tools / Log4brains	記録したいのがアーキテクチャ上の決定だけの場合。ADR はより簡潔で規律ある形式です。katra の decide は、あえて軽量にしたその類似ツールです。
Obsidian、Logseq、wiki	メモが個人的なもので、複数のプロジェクトにまたがっており、リポジトリ内に置くことが目的ではない場合。katra はリポジトリごとに使い、意図的にコミットします。
Hugo、Jekyll、Astro	公開ブログを書く場合。これらにはテーマ、フィード、分類体系、読者がいますが、katra にはそうしたものはなく、必要としていません。
Notion、Linear、Jira	担当者、権限、チームで共有するワークフローが必要な場合。katra のタスクはエントリーからリンクするためのものであり、チーム運営を担うものではありません。
git log と良いコミットメッセージ	正直なところ、多くの場合はこちらで十分です。コミットにすでに理由が記されていて、スクリーンショットも必要ないなら、これを使う必要はありません。

これらのツールにはなく、このツールが存在する理由は、リポジトリ内にログを残し、作業後ではなく作業中に記録し、スクリーンショットやインタラクティブなコンポーネントをインラインで含め、いずれにせよ行うコミットで公開することです。この4つすべてが必要でなければ、上記のいずれかのほうが適しており、より長年の実績があります。

インストール

macOS、Linux、Windows 向けに、amd64 と arm64 のバイナリを提供しています。

go install

主要な配布方法であり、最初のリリースが公開される前に使える唯一の方法です（下記の Homebrew とバイナリのダウンロードを参照）。Go 1.25 以降をすでにお使いの場合は、こちらが適しています。

go install github.com/craigjmidwinter/katra/cmd/katra@latest
go install github.com/craigjmidwinter/katra/cmd/katra-mcp@latest

両方をインストールしてください。katra-mcp は任意の追加ツールではありません。スキルとすべての MCP クライアント設定は、katra と並んで PATH 上にあることを前提としています。

go install でビルドすると、インストールしたバージョンが報告されます。go install …@v0.1.0 では v0.1.0 が報告され、作業ツリーからインストールすると、コミットを示す疑似バージョンが報告されます。リリースバイナリと make build には、代わりにリンク時のスタンプが付き、これによってダーティーなツリーであることも示されます。

ソースからビルドする

git clone https://github.com/craigjmidwinter/katra
cd katra
make install        # both binaries into GOBIN, version stamped

katra は自身を使って開発しており、./katra は katra 自身のログが置かれるディレクトリなので、make build はリポジトリのルートではなく ./bin/ に出力します。

リリースに何が含まれるかを確認したい場合は、make snapshot でリリース用アーカイブ一式をローカルでビルドできます（goreleaser が必要です）。

Homebrew

まだリリースは公開されていないため、v0.1.0 が公開されるまではこの tap からインストールできるものはありません。公開する手順は RELEASING.md に記載されています。公開後は、以下の説明が正確なものになります。

brew install craigjmidwinter/tap/katra

これは craigjmidwinter/homebrew-tap を tap として追加し、ビルド済みバイナリをインストールします。brew upgrade katra で新しいリリースに更新できます。

バイナリをダウンロードする

Homebrew と同様、これらのアーカイブはリリースのワークフローで作成されるため、v0.1.0 から利用可能になります。現時点ではまだありません。今後、リリースが公開されるたびに、macOS、Linux、Windows 向けのアーカイブが amd64 と arm64 の両方について用意されます。それぞれに katra と katra-mcp の両方に加え、checksums.txt とその署名が含まれます。

macOS または Linux（bash/zsh）の場合：

# Latest release, without the leading v. Set this by hand to pin a version.
VERSION=$(curl -fsSL https://api.github.com/repos/craigjmidwinter/katra/releases/latest \
  | sed -n 's/.*"tag_name": *"v\{0,1\}\([^"]*\)".*/\1/p')

OS=$(uname -s | tr '[:upper:]' '[:lower:]')     # darwin | linux
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')

curl -fsSLO "https://github.com/craigjmidwinter/katra/releases/download/v${VERSION}/katra_${VERSION}_${OS}_${ARCH}.tar.gz"
tar xzf "katra_${VERSION}_${OS}_${ARCH}.tar.gz" katra katra-mcp
sudo install -m 0755 katra katra-mcp /usr/local/bin/

Windows（PowerShell）の場合は、お使いのマシンのアーキテクチャに合った zip をダウンロードし、両方の .exe ファイルを PATH 上のディレクトリに展開します。

$release = Invoke-RestMethod https://api.github.com/repos/craigjmidwinter/katra/releases/latest
$version = $release.tag_name.TrimStart('v')
$arch = if ([Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString() -eq 'Arm64') { 'arm64' } else { 'amd64' }
$archive = "katra_${version}_windows_${arch}.zip"

Invoke-WebRequest "https://github.com/craigjmidwinter/katra/releases/download/v${version}/${archive}" -OutFile $archive
Expand-Archive $archive -DestinationPath katra-bin

macOS では、自分でダウンロードしたバイナリは Gatekeeper によって隔離されます。xattr -d com.apple.quarantine /usr/local/bin/katra で隔離を解除するか、上記の Homebrew インストールを使ってください。こちらでは隔離が解除されます。

ダウンロードしたものを検証する

curl -fsSLO "https://github.com/craigjmidwinter/katra/releases/download/v${VERSION}/checksums.txt"

# Linux
sha256sum --check --ignore-missing checksums.txt
# macOS
shasum -a 256 --check --ignore-missing checksums.txt

Windows では、Get-FileHash $archive -Algorithm SHA256 を実行するとアーカイブのハッシュが表示されます。展開する前に、checksums.txt 内の該当する行と照合してください。

次に、checksums.txt の署名を確認します。リリースはcosignでキーレス署名されているため、取得する公開鍵はなく、誰かが保管しなければならない秘密鍵もありません。署名証明書はリリースワークフロー自体の GitHub OIDC ID に発行され、公開 Rekor 透明性ログに記録されます。つまり、確認しているのは「このリポジトリの release.yml が、タグからこれをビルドした」ということです。

curl -fsSLO "https://github.com/craigjmidwinter/katra/releases/download/v${VERSION}/checksums.txt.sig"
curl -fsSLO "https://github.com/craigjmidwinter/katra/releases/download/v${VERSION}/checksums.txt.pem"

cosign verify-blob \
  --certificate checksums.txt.pem \
  --signature checksums.txt.sig \
  --certificate-identity-regexp '^https://github\.com/craigjmidwinter/katra/\.github/workflows/release\.yml@refs/tags/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  checksums.txt

アップグレード

上記の go install ...@latest コマンドを再実行すると、バイナリがその場で置き換えられます。2 回目の実行で両方が再リンクされることを、1 回目と同様に確認済みです。リリースが公開された後は、brew upgrade katra で Homebrew チャネルを同様にアップグレードできます。

アンインストール

katra setup は 5 つのものを作成し、それぞれ個別に削除できます。

1. git post-commit フック。 katra hook uninstall を実行します。
2. hub の launchd エージェント。 katra hub install を実行した場合に作成されます。katra hub uninstall で元に戻せます。launchctl unload を実行し、plist を削除します。
3. Claude Code スキル。 rm -rf .claude/skills/katra/ を実行します（ここには SKILL.md が 1 つあります）。
4. .claude/settings.json の hooks ブロック。 SessionStart、UserPromptSubmit、PostToolUse、Stop、PreCompact、SessionEnd キーの下にある katra agent-hook エントリを削除します。コミットゲートをインストールした場合は、PreToolUse も削除してから、空になったキーを削除してください。katra setup が追加したのは、これらのキーの下のエントリだけです。それ以外はユーザー自身の設定です。
5. ~/.config/katra/registry.yml のレジストリエントリ。 明示的な登録解除コマンドはなく、上記の操作でも削除されません。katra/config.yml が存在する限り残ります。自動化のアンインストールはログを手放すことと同じではないため、通常はそのままで問題ありません。katra/ を削除した場合は、次に katra hub list または katra hub serve がレジストリを読み込むときに、そのエントリは自動的に削除されます。すでに実行中の hub デーモンも対象です。

上記の操作で katra/ 自体が変更されることはありません。katra/ ディレクトリはユーザーのデータであり、そのまま残ります。

クイックスタート

git リポジトリ内で、約 5 分で完了します。

1. コーディングハーネスにリポジトリを結び付けずにセットアップします。

   katra init --install-hook
   

   ✓ katra created at katra
     entries/   — one markdown file per post
     media/     — images, gifs, video, html embeds
     config.yml — title, accent, hook behaviour
     registered with the global katra registry (…)
   ✓ post-commit hook installed at .git/hooks/post-commit
   

   katra/、ウェルカム下書き、移植可能な Git 自動スタンプフック、hub 登録を作成します。Claude Code ユーザーは、セッション通知を追加する katra setup --no-gate、または通知とコミットゲートを追加する katra setup を重ねて設定できます。

2. ウェルカム下書きに内容を追加し、スクリーンショットを挿入します。

   katra append --entry hello-katra "The first reason this project needs a chronicle."
   

   ✓ appended to hello-katra
   

   これは任意ですが、見せられるものができたら実際に行う価値があります。マシン上の画像をキャプチャしてください（macOS であれば、screencapture -x shot.png で画像を取得できます）。

   katra capture ~/Desktop/swing.png --entry hello-katra --caption "first visible proof"   # swap in your own path
   

   ✓ imported media/swing.png
   ✓ added to hello-katra
   

3. 配信します。

   katra serve
   

     local:   http://localhost:8080/
     network: http://192.168.1.23:8080/   (one line per LAN interface)
     watching katra — open tabs reload on change. Ctrl-C to stop.
   

   そのまま実行しておくと、開いているタブは書き込むたびに再読み込みされます。

4. 通常どおりコミットします。

   git commit -m "Reworked the swing arc"
   

   post-commit フックが、そのコミットのハッシュと diffstat を下書きに記録します。フックを使わない場合は、katra stamp（HEAD）、または複数のコミットからなるチャプターには katra stamp --hash a1b2c3,d4e5f6 を実行します。

5. 反映されたことを確認します。

   katra list
   

   2026-08-20 16:06:54  Reworked the swing arc   [12acf46]  (+261 −0)
   

   すでに作成したコミットに基づく、スタンプ済みのエントリです。このクイックスタートを締めくくる、確実に目で確認できる成功例です。

静的コピーを公開するには、次のようにします。

katra build --out ./site

外部リクエストを必要としない、自己完結型のディレクトリ（index.html、data.json、メディア）です。どこにでもホストでき、USB メモリから開くこともできます。

リッチコンポーネント

コンポーネントとは、言語名で指定するフェンス付きコードブロックです。ソースは読みやすく、差分も確認できます。ページにはウィジェットが表示されます。

```compare
before: media/bunker_before.png
after:  media/bunker_after.png
caption: Bunker reshape
```

```gallery
- src: media/a.png
  cap: tier one
- src: media/b.png
  cap: tier two
```

```video
src: media/horde.mp4
loop: true
```

```embed
src: media/frame-times.html
height: 480
caption: Frame time vs district count
```

```note
A callout. **Markdown** works inside it.
```

```warning
Same, with a warning style.
```

通常の ![caption](media/x.png) 画像には、ライトボックスが自動で付きます。

登録されていない言語は、通常のコードブロックとして表示されます。 これは形式の互換性ルールであり、フォールバックではありません。新しい katra 向けに書かれたエントリーも、古い katra で表示できます。ただし、見栄えは多少劣ります。

意図的にチャートコンポーネントは用意していません。自己完結型の HTML 図を作成してキャプチャすると、katra capture が .html を認識して embed ブロックを出力します。そのため、固定された種類から選ぶのではなく、描画できるチャートならどれでも利用できます。 examples/media/frame-times.html に実例があります。また、examples/entry.md では、1 つのエントリーですべてのコンポーネントを試せます（CI がプッシュのたびにレンダリングするため、古くなりません）。

コンポーネントの追加は、internal/core/render.go に ComponentFunc を 1 つ追加するだけです。これが拡張できるすべてです。詳しいリファレンスはこちらです： docs/components.md。

ディスク上のレイアウト

katra が書き込むファイルは、その公開 API です。 リポジトリに保存される Markdown なので、ツールがなくても読め、ツールより長く残ります。

katra/
  config.yml        title, accent, hook behaviour, memory settings
  entries/          one .md per post
  tasks/  epics/  decisions/  articles/
  media/            images, gifs, video, html embeds
  .state/           machine state — ledger, receipts (gitignored)

---
title: Reworked the swing arc
date: "2026-08-03"
tags: [physics, gameplay]
hash: 5ddc0f5          # or  hashes: [a, b]  for a chapter of commits
stat: {f: 12, a: 340, d: 50}
summary: tuned the magnus model      # optional, for the index
featured: true                       # optional → "Deep Dives" zone
cover: media/hero.png                # optional banner image
---

Markdown body. Write the *why*, not a paraphrased diff.

config.yml があるディレクトリだけが katra として認識されます。標準の名前は katra/ です。名前変更前の devlog/ も引き続き検出されるため、以前のリポジトリも移行せずに使い続けられます。

利用側が前提にできる互換性ルールは次のとおりです。不明なフロントマターキーは無視され、不明なフェンスはコードブロックとして表示され、type がない場合は entry として扱われます。完全な仕様はこちらです：docs/format.md。

コマンド

コマンド	説明
katra setup [--no-gate]	Claude Code のスキル／フックに加え、Git の自動スタンプとハブ登録を追加します。何度実行しても安全です。
katra init [--title T] [--install-hook]	ハーネスに依存しない Katra をひな形から作成します。Git の自動スタンプも必要に応じて設定できます。
katra new "Title" [--tags a,b] [--featured]	下書きエントリーを作成します。
katra append [text] [--entry slug] [--file -]	下書きに Markdown を追記します。
katra capture <file> [--caption C]	メディアをアクティブな下書きに取り込みます。
katra compare <before> <after>	ビフォー／アフターのスライダーを追加します。
katra stamp [--hash H…] [--closes task]	コミットと差分統計を下書きに記録します。
katra list [--drafts] [--json]	エントリーを一覧表示します。
katra serve [--port N]	LAN 上で自動リロードされるページを起動します。
katra build [--out dir] [--all]	静的サイトをビルドします。
katra hook install | uninstall	自動スタンプ用の Git フックを管理します。
katra doctor	参照先のないメディア、解析エラー、ビジュアルのないエントリー、古くなったエピックを検出します。
katra task | epic | decide | article	ノードモデルです。
katra task spec <slug> <ref>	タスクをコミット済みの仕様に関連付けます（todo／空 → specced）。
katra reconcile …	現在の作業の目的を宣言します。
katra memory scan | status	Claude Code のメモリを取り込みます。
katra hub serve | list | scan | install	登録済みのすべての katra を対象にします。

完全なリファレンスはこちらです：docs/cli.md。

Git 連携

katra stamp は git を使ってハッシュを解決し、差分統計（--numstat）を算出します。オプションの post-commit フックを使うと、「スタンプし忘れた」という問題を完全になくせます。

katra hook install

各コミットの後に、そのコミットを使ってアクティブな下書きにスタンプします。ただし、フック自身の記録用コミットと katra だけを変更するコミットはスキップします。デフォルトではスタンプは作業ツリーの変更として残るため、自分でコミットできます。フックにコミットさせるには、config.yml で autoCommit: true を設定します。

このフックは core.hooksPath に対応しています。husky の場合、追跡対象の .husky/post-commit にインストールされます。npm install のたびに書き換えられる生成物の .husky/_/ にはインストールされません。生成物の shim は、追記した内容が実行される前に終了するためです。

ハブ

katra はリポジトリごとに使うもので、ログには適していますが、「自分が何をしていたか」を振り返る用途には適していません。

katra hub serve          # http://localhost:4200 — every registered katra
katra hub install        # run it at login (macOS launchd)

プロジェクト全体のインデックス、複数プロジェクトを横断するボードとロードマップ、統合された時系列ログに加え、各プロジェクトのビューアーを /p/<id>/ で表示できます。レジストリは ~/.config/katra/registry.yml にあり、読み込み時に副作用として不要な項目が整理されるため、削除したプロジェクトはクリーンアップを行わなくても表示されなくなります。

katra build --all を実行すると、静的ディレクトリと同じものが生成されます。ホスト型サービスも、アカウントも、同期機能もありません。docs/hub.md を参照してください。また、contrib/ には launchd エージェントと systemd ユニットがあります。

コントリビューション

PR を歓迎します。セットアップ方法、テストと lint のコマンド、変更時に守るべき不変条件については、CONTRIBUTING.md をご覧ください。RELEASING.md では、リリースの実際の公開手順を説明しています。リリースを行う方はご確認ください。

ステータスと対象範囲

バージョン 1.0 以前で、作者が自分のプロジェクトで使うために書いたものです。「実戦で十分に検証済み」という言葉は簡単に口にでき、簡単に確かめられるので、具体的な実績を示します。11 個のリポジトリ、237 件のエントリー、4 か月以上。 利用頻度は毎日ではなく、ばらつきがあります。7 月は 31 日中 24 日にエントリーが作成されるほど集中的に使われましたが、その前の 3 か月は利用がまばらでした。

まだ他の人は使っていないため、皆さんが遭遇する不具合は、おそらくこれまで誰も遭遇していないものです。

支持する点が 2 つ、反対する点が 1 つあります。いずれも確認できます。

• ディスク上のフォーマットが安定している部分です。これは Markdown であり、上記の互換性ルールを意図的に守っています。
• このツールは自身の開発にも使われているため、このリポジトリの katra/ はデモではなく、実際の出力例です。
• これほど多くのリポジトリで連携を維持するのは、実際に難しいことがわかりました。 8 月の監査では、スタンプのない下書きが 40 件、エントリーを一度もスタンプしていないプロジェクトが 3 件、エージェントフックが壊れているか欠落しているプロジェクトが 11 件中 9 件見つかりました。その大半は katra 側の問題でした。フックのインストーラーが husky に再生成されるディレクトリに書き込んでおり、ハブは起動時のレジストリのスナップショットを使っていました。この 2 つは修正済みです。ただし、率直に言えば、自動化は失敗を知らせるべきところで十分に知らせていませんでした。katra doctor の実行をおすすめします。

コマンド名やフラグは、今後変更される可能性があります。

意図的に対象外としているもの

• ホスト型サービス。 ログはリポジトリ内の Markdown です。ログインする必要も、移行する必要もありません。バックエンドを追加すれば、利便性と引き換えにその利点が失われます。
• 汎用コンテナーへのインストール。 katra は作業ツリー、git の履歴、フックを使います。ツール全体をコンテナー化するには、これら 3 つすべてをマウントする必要があり、そうするとローカルにインストールするより不便になります。リリースワークフローでは、公式 MCP Registry がインデックスを作成できるように、最小限の katra-mcp OCI ラッパーをビルドします。上記のインストール方法に代わるものではありません。
• テーマシステム。 ビューアーのデザインは 1 種類で、調整できるのは accent です。必要であれば、静的ビルドのディレクトリを自分で再スタイリングできます。
• フィード、コメント、分析機能。 リポジトリに参加している人向けのログです。
• 差分の要約。 katra が差分からエントリーを作成することはありません。差分だけでは わからない ことこそが重要であり、自動生成されたエントリーは、このツールが避けようとしている単なる言い換えになってしまうからです。

既知の制限事項

• ハブの launchd エージェントを正式にインストールできるのは macOS のみです。 contrib/systemd/ で Linux に対応していますが、 katra hub install はありません。

• katra serve と katra hub serve はすべてのインターフェースにバインドするため、LAN 上のヘッドセットやスマートフォンからアクセスできます。認証機能はありません。信頼できないネットワークでは実行しないでください。

• スラッグを変更すると、受信側の [[wikilinks]] が壊れます。 ファイルパスが識別子です。katra doctor はその結果生じたリンク切れを報告しますが、リンクを書き換えることはありません。

• メディアはコミットされます。 GIF だらけのログは、GIF だらけのリポジトリになります。Git LFS は使えますが、katra はその存在を認識も気にもかけもしません。

• stat の diffstat はエントリーに関係のないファイルも含め、コミット全体を集計します。 チャプターの場合は、複数のコミットにわたる合計です。規模を把握するためのものであり、厳密な記録ではありません。

• katra build が上書きするのは、生成するファイルだけです。 index.html、app.js、styles.css、data.json はビルドのたびに書き換えられます。それらと並べて追加したファイルには手を加えません。この組み合わせが落とし穴です。ディレクトリ全体を上書きするジェネレーターなら、注意して使うことを学べます。しかし、このジェネレーターは追加したファイルをそのまま残すため、編集内容全般も保護されると考えるのはもっともです。そして、生成ファイルの内部に加えた唯一の編集が破棄されます。

  ページに手作業で追加したもの、たとえばアナリティクスのスニペット、ソーシャルタグ、ファビコンのリンクなどは、次のビルドで気づかれないまま消えます。ページは問題なく表示され続ける一方で、それらが機能させていたものは停止しています。このような挿入内容は、ビルドの後に実行するステップに含めてください。新たにビルドしたファイルにそのステップを適用し、コミットしたファイルが再現されることを確認してください。ページが正しく表示されることは、一度は機能した証明にはなりますが、現在も機能している証明にはなりません。

• ビルドされたサイトの URL は 1 つだけなので、各エントリーに個別の URL はありません。 ビューアーはフラグメント（#/node/<slug>）でルーティングしますが、ブラウザーはフラグメントをサーバーに送信しません。重要な場所で katra を公開する前に知っておくべきことが 2 つあります。

  • すべてのエントリーでソーシャルカードが共通になります。 スクレイパーが取得できるエントリーごとの URL がないため、どのエントリーへのリンクも、そのエントリーではなくサイトとして展開されます。存在する唯一のページにタグを設定しても、これは変わりません。
  • アナリティクスで数えられるのは、エントリーを読むごとではなく、訪問ごとに 1 ページビューです。 エントリー間の移動はフラグメントの変更であり、ナビゲーションは発生しません。20 件のエントリーを読む読者も 1 ページビューとして記録されるため、エントリーごとの閲覧数は不正確なのではなく、そもそも取得されません。

  これは 2 つではなく 1 つの制限であり、どちらか一方だけを解決することはできません。どちらにもエントリーごとの URL が必要です。ビルド済みページに head タグを挿入しても、どちらも解決しません。サーバーがルーティングしないカードの内容は変えられず、発生しないナビゲーションを発生させることもできません。

  サーバーから認識できるエントリーごとのページは計画中です。公開済みの #/node/<slug> リンクは、それらのページが実装された後も引き続き機能します。それまでは、katra は公開してリンクを張れる記録ですが、個々のエントリーにリンクしたり、プレビューしたり、閲覧数を数えたりすることはできません。

ドキュメント

https://midwinter.io/katra/ で閲覧できます。または、このリポジトリ内をご覧ください。

• docs/quickstart.md — インストールから最初のスタンプ付きエントリーまで。
• docs/workflow.md — ハーネスに依存しない、仕様からスタンプまでのワークフロー全体。
• docs/components.md — すべてのコンポーネント、それぞれが受け取る正確なキー、チャートや図の作成方法。
• docs/cli.md — すべてのコマンドとフラグ。
• docs/configuration.md — すべての config.yml キー、そのデフォルト値、エラー時の動作。
• docs/format.md — ディスク上のデータ形式に関する仕様。katra を扱うツールを作成する前にお読みください。
• docs/agents.md — CLI、15 個の MCP ツール、オプションの Claude スキル、フック、コミットゲート、メモリーの取り込み。
• docs/hub.md — レジストリとプロジェクト横断ビュー。
• docs/architecture.md — 境界部分と、変更を加えるべき場所。
• CONTRIBUTING.md — ビルド、テスト、コードベースで定めている規約。

実行可能な例：examples/entry.md（CI によってレンダリングされる、すべてのコンポーネントを含む 1 つのエントリー）、examples/config/（最小限の設定と、詳細なコメント付きの設定）、examples/media/frame-times.html（単体で動作するチャート）。

謝辞

ロゴタイプには、Undercase Type（Phaedra Charles、Flavia Zimbardi）による Fraunces を使用しています。SIL Open Font License 1.1 の下で利用しています。ブランドアセット、カラーパレット、および測定済みのコントラスト比は、branding/BRAND.md にあります。

ライセンス

MIT。LICENSE をご覧ください。