TokenKnows — distill AI coding sessions into weekly reports, ADRs and a knowledge graph

TokenKnows

AI コーディングセッションから生きたナレッジを抽出します。週次レポート、ADR、インシデントレビュー、書籍、エージェントスキル、ナレッジグラフを作成します。

英語 | 簡体字中国語

---

TokenKnows とは？

Claude Code、Codex、Cursor と何時間もペアプログラミングをしても、セッション中の決定事項、バグ調査、設計上のトレードオフは、ターミナルを閉じた瞬間に消えてしまいます。TokenKnows はそれらを自動的に記録し、根拠にひも付いた構造化ナレッジアセットへと抽出します。

記録（6 種類のコレクター）→ 抽出（5 段階の LLM パイプライン）→ アセット（7 種類のドキュメント）→ レビュー／墨消し／公開

• 📡 あらゆる情報を記録 — Claude Code、Codex、Cursor、VS Code、GitHub の PR／コミット／Issue、ローカルドキュメントを、ローカルのファイル監視と API ポーリングで収集します。Webhook もトンネルも不要です。
• 📝 7 種類のアセット — 週次レポート、技術設計書、ADR、インシデントレビュー、長編書籍、再利用可能なエージェントスキル（SKILL.md）、エンティティナレッジグラフに対応します。
• 🔗 根拠にひも付いた記録 — すべての段落から元の PR／会話／コミットをたどれます。2 つ以上のソースにわたり、cosine × trust × recency に基づいて順位付けします。
• 🔒 ローカル優先、既定では外部送信ゼロ — 3 層の LLM 外部送信ゲート（インスタンス ∧ プロジェクト ∧ タスク）と完全な監査ログを備えています。Ollama と組み合わせれば、クラウドキーなしでパイプライン全体を実行できます。

Demo

Workbench	Document page
Evidence drawer	Publish receipt + version diff

▶ Full walkthrough: engineering_handoff/walkthrough.mp4 (5 min, Chinese narration + subtitles)

All 12 screens

1 Workbench	2 Event drawer	3 Document list	4 Document page
5 Evidence drawer	6 Regenerate dialog	7 Review	8 Redaction
9 Publish dialog	10 Publish receipt + diff	11 LLM egress	12 Admin

プラグインをインストールする

前提条件：TokenKnows バックエンド（http://localhost:8001）およびウェブ UI（http://localhost:5173）（クイックスタートを参照）、ならびに uv（プラグインは uvx 経由で MCP サーバーを PyPI から取得します）。すべてのプラグイン環境変数にはローカル環境で動作するデフォルト値が設定されています。デフォルト以外の設定を使う場合に限り、TOKENKNOWS_API_BASE / TOKENKNOWS_API_TOKEN / TOKENKNOWS_DEFAULT_PROJECT / TOKENKNOWS_WEB_BASE をエクスポートしてください。ウェブ UI で登録／ログインし、バックエンドで認証が必要な場合は Project Settings → MCP 接入 で API トークンを作成してください。

プラットフォーム	方法
Claude Code	/plugin marketplace add johnnywuj81/tokenknows → /plugin install tokenknows@tokenknows — 詳しい手順は tokenknows-plugin/README.md を参照（5 分でできるクイックスタート）
Codex	codex plugin marketplace add johnnywuj81/tokenknows → codex plugin add tokenknows@tokenknows（スキル、コマンド、MCP サーバーを読み込みます。ローカルクローンを使う方法は codex-plugin/README.md を参照）
Cursor	tokenknows の MCP ブロックを ~/.cursor/mcp.json に追加します（uvx の設定例は code/tokenknows-mcp/README.md を参照）
VS Code	Releases から .vsix をダウンロードし、code --install-extension tokenknows-vscode-*.vsix を実行します

このプラグインは、AI ツールに MCP ツール（submit_session_events、distill_document、list_assets、get_asset、get_asset_chapters、search_entity）と、/tokenknows:weekly や /tokenknows:adr などのスラッシュコマンドを追加します。

クイックスタート

# 1. (Optional but recommended) Ollama — fully local inference, zero cloud keys
ollama serve &
ollama pull minimax-m2:cloud          # or gpt-oss:20b, qwen2.5, ...

# 2. Backend (FastAPI + SQLite persistence + 3-layer LLM egress gate)
cd code/tokenknows-api
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
cp .env.local.example .env.local      # defaults to Ollama; edit to add cloud providers
.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8001

# 3. Frontend (React 19 + Vite)
cd code/tokenknows-web
npm install
npm run dev
# open http://localhost:5173 — talks to the real backend (mocks are opt-in via ?msw=1)

# (Optional) seed demo data
./engineering_handoff/demo-seed.sh

プラットフォームのサポート：macOS — すべての機能を利用できます（コレクターは launchd 経由で自動起動します）。Linux — バックエンド、フロントエンド、コレクターはすべて手動で実行します（python3 plugins/<x>/sync.py --watch）。launchd スクリプトは使用できません。Windows — 未テストです。WSL2 の使用を推奨します。

データコレクター

すべてローカルで動作し、ngrok もパブリック Webhook も不要です。macOS ではクラッシュ時および再起動時に自動で再起動します（launchd）。

コレクター	ソース	モード
claude-code	~/.claude/projects/*.jsonl	30 秒間隔でポーリング、増分オフセット
codex	~/.codex/sessions/**/rollout-*.jsonl	30 秒間隔でポーリング、増分オフセット
cursor	Cursor の state.vscdb（読み取り専用 SQLite）	60 秒間隔でポーリング
github	GitHub REST API · PR／イシュー／コミット	5 分間隔でポーリング（gh auth トークン）
vscode	VS Code 拡張機能の onDidSaveTextDocument	バッファリング、10 秒間隔でフラッシュ
local-docs	~/Documents 内の .md .txt .pdf（watchdog）	リアルタイム、2 秒のデバウンス

./scripts/launchd/install.sh          # macOS: install all 5 Python collectors as LaunchAgents
launchctl list | grep com.tokenknows
tail -f ~/Library/Logs/tokenknows/*.log

各イベントには信頼スコア（0.6 × source_authority + 0.4 × extraction_confidence）が付与されます。エビデンス段階では、引用を 0.6 × cosine + 0.25 × trust + 0.15 × recency でランク付けし、2 つ以上の異なるソースを必須とします。

アーキテクチャ

コレクターはイベントストア（SQLite）にデータを送ります。5 段階のパイプライン（collect → outline → content → evidence → assess）がイベントをアセットに変換します。LLM Gateway は、タスクごとのルーティングとフォールバックチェーンを備え、4 つのプロバイダー（Anthropic / OpenAI / MiniMax / Ollama）を統合します。また、3 つすべての外部送信スイッチがオンでない限り、クラウドへの呼び出しを拒否します。

CI

ワークフロー	ランナー	トリガー
ci.yml	ubuntu-latest（GitHub ホステッド）	main へのプッシュ、およびすべての PR
ci-macos.yml	セルフホスト macOS ARM64	メンテナーによる main へのプッシュのみ — 外部 PR のコードは実行されません

プライバシーとローカルファースト

• デフォルトでは外部送信はありません。クラウド LLM の呼び出しには、インスタンス、プロジェクト、タスクのすべてのスイッチをオンにする必要があります
• 独自のキーを使用できます。監査ログがマシンの外に出ることはありません
• ワンクリックのキルスイッチで、インスタンスを完全オフラインモードに切り替えられます

詳細：PRD §6.7 データレジデンシーと外部送信制御（中国語）。

ドキュメント

トピック	ドキュメント
プロダクト要件、ユーザージャーニー	PRD (zh)
技術設計、API、スキーマ	TDD (zh)
全体アーキテクチャとマイルストーン	Architecture (zh)
画面ごとのエンジニアリング上の決定事項	TaskTechDesign (zh)
ピクセル単位のUIモックアップ	mockups/ — ブラウザーで開く

詳細なドキュメントの大半は、中国語（プロジェクトの作業言語）で書かれています。コードコメントも主に中国語です。英語または中国語でのIssueやPRを歓迎します。

コミュニティ

CONTRIBUTING · Roadmap · Code of Conduct · Security policy · Issues

ライセンス

MIT © 2026 johnnywuj81