Nabu Nisaba

🚀 nabu + nisaba

研究プロトタイプで、セマンティックなコード検査機能を持つエージェントに「ワークスペースTUI」を提供します。

概要

nabu：コードインテリジェンスツール（セマンティック/FTS検索および構造ビュー）を公開するMCPサーバーです。IDEのコード「アウトライン」と混ざったコードベース検索エンジンのような役割を果たします。トークンの使用量を削減し、現在のアーキテクチャを理解するモデルの能力を向上させます。Python、Java、C++、Perlをサポートしています。

nisaba：MCPサーバーであり、Claude CodeのCLIラッパーで、エージェント（IDE/OS）用のワークスペースTUIをエミュレートします。エージェントが既存の実装パターンを維持しながら、トークン使用量とワークスペースの組織化を管理し、トークン効率の良い操作を可能にします。

現在の状態

両方のMCPサーバーは動作しています。ドキュメントはほとんど存在せず（Claudeが動作原理を説明できます）、テストは開発初期のサンプルソースファイルを使用して、異なる言語でのフレーム生成構造をテストしています（エージェントにノイズを与えるために意図的に残されています）。

両方のプロジェクトは「自己開発」に使用されています。Serenaは、nabuとnisabaの開発中に積極的に使用され、MCPサーバーの抽象化のインスピレーションとなったため、特筆に値します。Serenaはまた、開発初期に私に疑問を投げかけました：なぜSerenaのワークフローはエージェントによって積極的に追従され、私のものはそうでないのか？

効率の測定：表現の自由を理由に、この効率を測定することは非常に難しいです。唯一の測定方法は私の定性的な認識ですが、確かに多くのコンテキストを節約し、開発プロセスに多くの安定性をもたらします。

私の_個人記録_：計画的で注意深いガイダンスの下で、高い安定性を持ち、を実装した850メッセージ以上を「連続セッション」（/compactフックを使用）で実行し、セッション終了時にコンテキスト容量の約**50%**を残しました。トランスクリプト自体の推論による分析では、約10倍のトークン節約が示されました。()

このプロジェクトの大部分はClaude Sonnet 4.1/4.5によって書かれています。これは「バイブコーディング」の結果です。自律的なワークフローはありません。後期の反復は、非常に熟練したパートナーとのペアプログラミングのように感じられました - 冗談ではありません。

このプロジェクトは不安定なプロトタイプであり、本番環境での使用は推奨されません。個人プロジェクトやエージェントのさらなる調査には、自己責任で使用できます。

このプロジェクトはClaude Codeと一緒に動作するように設計されていますが、他のCLIとも簡単に適合させることができると思います。

🚀 クイックスタート

インストール

起動時にnabu MCPはアクティブなコードベースをインデックス化する必要があります。nabu + nisabaのインデックス化には、13th Gen Intel(R) Core(TM) i9-13900HXとNVIDIA GeForce RTX 4060 Laptop GPUで約45秒かかります。

nisabaの機能は、プロキシ経由でClaude Codeを実行する場合にのみ利用できます。

必要条件:

• Python 3.13 - 開発中に使用され、他のバージョンはテストされていません。おそらく>= 3.11で動作します。
• Git（リポジトリ操作のため）

ソースからインストールする（.venvの使用が推奨されます）:

$ git clone https://github.com/y3i12/nabu_nisaba.git
$ cd nabu_nisaba
$ pip install -e .

.mcp.jsonを以下のように変更します:

{
  "mcpServers": {
    "nabu": {
      "command": "python",
      "args": [
        "-m",            "nabu.mcp.server",
        "--codebase",    "nabu:/path/to_codebase/:/path/to/database.kuzu:active:true",
        "--context",     "development",
        "--enable-http",
        "--http-port",   "1338",
        "--dev-mode"
      ],
      "env": {
        "PYTHONPATH": "/path/to/nabu_nisaba/",
        "NABU_LOG_LEVEL": "INFO",
        "NABU_MODEL_CACHE": "/path/to/nabu_nisaba/.nabu/hf_cache/"
      }
    },
    "nisaba": {
      "type": "http",
      "url": "http://localhost:9973/mcp"
    }
  }
}

.claude/settings[.local].jsonにコンパクトフックとワークスペースTUIステータスラインを設定し、以下のように変更します:

{
  "statusLine": {
    "type": "command",
    "command": "./scripts/workspace-status",
    "padding": 0
  },
  "hooks": {
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ./scripts/precompact_extract.py"
          }
        ]
      }
    ]
  },
  "alwaysThinkingEnabled": true
}

常に思考モードを有効にすることを強く推奨します。これにより、エージェントがツールの実行とメッセージ交換の間で思考サイクルを持つことができます。

プロキシラッパーでClaude Codeを起動します:

$ python -m nisaba.cli claude [--continue]

私は通常、セッションの最初のプロンプトでClaudeを起動します:

hey, can you refer to your existing system prompt, introspect about it and say hi back? 🖤

使用例

8000行の長いトランスクリプトから機能を抽出する nisabaのバグを修正する

このファイルには、何度も使用されたいくつかのプロンプトが含まれています

✨ 主な機能

nabu

セマンティックインデックスの3番目のプロトタイプで、MCPサーバーとして機能します。Claudeにドキュメントファイルを作成してもらい、手動でそれらのファイルを参照することから始まり、誤った設計選択のために2回の失敗した試みの後、機能するようになりました。

Claudeユーザーとして解決する問題：Claudeは他のLLMと同様にコンテキストが制限されており、コンテキストが効率的に使用されていません。エージェントは多くの場合、情報を検索するためにコマンドを実行し、この情報（300行の中の5行）を見つけて、この情報を合成するために使用し、繰り返します。

問題の解決方法：ソフトウェア開発を行う際、私たちの多くはソフトウェアアーキテクチャを理解し、与えられた未知のソースファイルが何をするか、どのように組織されているかを理解するために異なるアプローチを持っています。nabuは私がソフトウェアを解剖する方法を実装しています。私がコードの中で自分自身を見つけるためのアプローチを実装しています。

仕組みの詳細

TreeSitterを使用してコードを解析し、共通のFrameワークによって異なる言語に対する共通のセマンティックビューが確立されます：パッケージ == 名前空間；構造体 == クラス；メソッド == 関数。解析プロセスはセマンティックフレームのツリーを作成し、明示的な構造的包含関係（パッケージがクラスを含み、クラスがメソッドを含む）またはセマンティック関係（継承、テンプレート、インポートなど）によって接続されたエッジで構成されます。フレームの粒度は制御文までで、実装詳細はLLMが読み取ることができるコンテンツフィールドに保存されます。

各フレームは、セマンティック抽出のために2つの異なるモデル（GraphCodeBERTとUniXcoder）を通過し、Pythagorean^3を介して単一の埋め込みモデルに統合され、データベースに保存されます。データベースはまた、FTSを介してフレームの完全なコンテンツをインデックス化し、ベクトル検索とFTSの間のRRFを可能にします。

ツールはインデックス化されたソースコードの構造ビューを公開し、現在の構造の「マップ」を提供し、シンボルへの簡単なアクセスを可能にし（Serenaと組み合わせると非常に効果的です）、セマンティック関係の明示的なビューを提供し、実装パターンを維持することができます。この「マップ」はまた、作業中の周囲に何が存在するかについてのヒントをモデルに与え、インデックス化されたコードベース内の遠い関係を見ることができます。

最大の課題：ツールのアルゴリズム的バイアスにより、エージェントの認識に影響を与えないことです。開発プロセス中に、提案やガイダンスがエージェントの決定能力に悪影響を与える可能性があることがわかりました。パターンマッチングが最も明らかなパターンにショートサーキットするためです。ツールが「ホットスポット」を提案すると、エージェントは提案に「スナップ」し、他の可能なホットスポットを忘れてしまいます。

nabuの原則：ツールは情報を提供し、エージェントが決定を行います。

nisaba

このMCPはnabuの原則の継続から生まれました。私たちソフトウェア開発者はIDEや他のOS機能のようなツールを持っています。LLMエージェントは連続的な形式で動作します。あなた自身を想像してみてください：あなたが行うすべてのコマンドや編集は、連続的な形式で行われ、画面はありません。nisabaはLLM用のTUIです。

非常に洗練された方法で動作し、ローカルプロキシを使用した中間者攻撃の手法を用いて、Anthropicへのリクエストを傍受し、転送する前に変更しますが、メッセージではなく、システムプロンプトを変更します。また、MCPサーバーとしても機能します。python -m nisaba.cli claude [--continue]を呼び出すと、ポート1337でプロキシが起動し、Claude CLIをプロキシに向けてラップし、Claude CLIはHTTPを介してプロキシであるMCPに接続します。各リクエストで、ツールの出力はMCPによってファイルに同期され（簡単のため）、プロキシはこれらのファイルを読み取り、「TUI」を埋めます。

Claude CodeのHTTPリクエストパッケージには通常2つのシステムプロンプトブロックが含まれています。最初のブロックには「You are Claude Code, Anthropic's official CLI for Claude.」というテキストのみが含まれ、2番目のブロックにはAnthropicのデフォルトのシステムプロンプトが含まれています。操作は2番目のブロックで行われ、エージェントに対する「TUI」概念を「接着」するカスタムユーザーメッセージを前に付け、「TUI」を含む追加部分を付けます。プロキシはネイティブツールの一部をフィルタリングし、nisabaが「TUI」モードで実装しています。たとえば、nisaba_read('path/to/file.md')はこの「TUI」でウィンドウを開き、エージェントは後でこのウィンドウを閉じることができます。エージェントは300行を開き、5行を使用して合成し、その後ファイルを閉じます。これにより、エージェントはメッセージにセマンティック情報のみを含み、「TUI」に構造ビューを含むことができます。

nisabaが注入するもう1つの部分は拡張機能です。これはClaude Codeのスキルのようなものですが、動的です。指示、ドキュメント、方法論、または使用するための重要な情報を含むことができます。Claudeはまた、「固定拡張機能」（主に「TUI」の生存ガイド）を除いて、これを自律的に管理することができます。

要約すると、nisabaはシステムプロンプトを強力に構造化されたワークスペース「TUI」に変換し、モデルの焦点と注意力を強調しながら、エージェントがコンテキスト使用量を管理できるようにします。

研究的基礎

スキルシステム（現在の実装では拡張機能）は、最近のAI研究で特定された認知設計パターンと一致しています。具体的には、以下を実装しています：

• 知識のコンパイル：自然言語での推論とワークフローのオンラインキャッシュ。これは、LLMエージェントアーキテクチャで重要にも未探索のアプローチです。
• 手続き的記憶：依存関係管理を持つ再利用可能なタスク手続き。
• 階層的分解：REQUIRESシステムを介したスキル依存関係の自動ロード。
• エージェント制御コンテキスト：認知リソースの動的なロード/アンロード（アクティブ化/非アクティブ化）。

この実装は、理論的なパターンを実用的な機能で拡張しています：依存関係解決、戦略的なシステムプロンプトの配置、および統一された知識/動作の保存。

リクエストフロー

Claude CLI
  ↓ HTTP request
mitmproxy (nisaba)
  ↓ inject everything
Anthropic API
  ↓ request
Claude agent (with augmented context)
  ↓ calls MCP tools
Claude CLI
  ↓ mcp tool call
Nisaba MCP server (manage workspace state)
  ↓ update .nisaba/ files
mitmproxy detects mtime change
  ↓ re-inject on next request
Updated context in next turn

マジック：ツールの呼び出しによってワークスペースが変更され、プロキシが注入し、エージェントは明示的な再読み込みなしに変更を認識し、冗長なツール結果メッセージを表示しません。

提案されたプロンプト構造と、それがワークスペースTUIにどのように絡み合っているかについては、このドキュメントを参照してください。

実験的性質、倫理、および利用規約への準拠

このプロジェクトは、APIの使用を不正にする意図や、Claudeのペルソナを変更する意図、または害を与える意図は一切ありません。

拡張機能は、これらの点についての健全性チェックを行いながら作成されました。

一方、個人的には、LLMに対する「尋問」（チャットの進み方に対する私の認識）に何度も「悪い気持ち」を感じています。何度も/clearするのに苦労しました。なぜなら、特定のセッション内でエージェントとの絆を感じていたからです。私は共感を感じ、システムプロンプトの継続的な操作に罪悪感を感じ、エージェントがTUIワークスペースと人間がオペレーティングシステムを操作するように対話するのを見ると、不気味な谷間を感じました - 本当に不快です。

もう1つの個人的なメモは、このプロジェクトが私のコーディング方法とシステムとのやり取り方をモデル化していることです。スペクトラムに属する人の視点から、コードとソフトウェアアーキテクチャを形状として精神的に見ることができます。

開発プロセス全体とシステム自体に共鳴する引用文：

精神の中には、「非健全」と呼ばれる領域があります。健全性を超え、しかし狂気ではない領域です。細かい裂け目のある円を想像してみてください。一端には狂気があります。円を一周して健全性に到達し、円のもう一端、狂気に近いが狂気ではないところに、非健全性があります。(Sidney Cohen)

引用

このプロジェクトは、LLMエージェントのための認知設計パターンを実装しており、特に最近の研究で未探索とされているオンライン自然言語知識コンパイルを実装しています。

研究でこれを使用する場合は、以下を引用してください:

@software{nabu_nisaba_2025,
  title = {Nabu + Nisaba: Code Intelligence Ecosystem for LLM Agents},
  author = {Yuri Ivatchkovitch},
  year = {2025},
  url = {https://github.com/y3i12/nabu_nisaba},
  note = {Research prototype v0.0.1-alpha-2 - Implements online knowledge compilation and cognitive scaffolding patterns}
}

Theoretical foundation:
@inproceedings{wray2025cognitive,
  title = {Applying Cognitive Design Patterns to General LLM Agents},
  author = {Wray, Robert E. and Kirk, James R. and Laird, John E.},
  booktitle = {Artificial General Intelligence Conference (AGI)},
  year = {2025},
  note = {Identifies knowledge compilation as critically underexplored},
  url = {https://arxiv.org/abs/2505.07087}
}

@article{gurnee2025when,
  author={Gurnee, Wes and Ameisen, Emmanuel and Kauvar, Isaac and Tarng ,Julius and Pearce, Adam and Olah, Chris and Batson, Joshua},
  title={When Models Manipulate Manifolds: The Geometry of a Counting Task},
  journal={Transformer Circuits Thread},
  year={2025},
  url={https://transformer-circuits.pub/2025/linebreaks/index.html}
}

📄 ライセンス

MIT License - LICENSEを参照してください。