ardathhomeless585/mini-coding-agent

mini-coding-agent は何をしますか？

Ollama、ワークスペーススナップショット、ツール使用、承認機能、永続メモリを備えたローカルコーディングエージェントで、より安全な自動コーディングを実現

このスキルは、ローカル環境で動作するミニマルなコーディングエージェントを構築するためのものです。Ollama を使用してコード生成と編集をローカルで実行し、ワークスペースのスナップショット機能により、各アクションの前後でファイルシステムの状態を比較できます。ツール使用（Tool Use）をサポートし、エージェントがファイルの作成・編集・削除、ターミナルコマンドの実行などを自律的に行えます。すべての操作は承認キューを通じて確認され、許可されたものだけが実行されます。永続メモリ機能により、エージェントはセッションをまたいでコンテキストや状態を保持し、長期的なタスクにも対応できます。

主な機能

• ローカルLLM: Ollama を介してローカルの大規模言語モデル（LLM）を使用します。
• ワークスペーススナップショット: 操作前後のワークスペース状態をスナップショットとして保存し、変更を簡単に比較・レビューできます。
• ツール使用: ファイル操作（読み取り、書き込み、パッチ適用）、ターミナルコマンド実行、ファイル検索などのツールをエージェントが使用できます。
• 承認キュー: 各ツール呼び出しは承認キューに入れられ、ユーザーが明示的に承認または拒否できます。これにより、自動操作を完全に制御できます。
• 永続メモリ: エージェントのメモリはファイルに保存され、セッション間で保持されます。

対応プラットフォーム

このスキルは以下のプラットフォームで動作するように設計されています：

• Claude Code （Anthropic）
• Cursor （Anysphere）
• Codex （OpenAI）
• その他、ツール使用と承認機能をサポートする任意のエージェントフレームワーク

セットアップ

前提条件

• ollama がインストールされ、実行中であること
• 少なくとも1つのモデルがプルされていること（例： codellama:7b、 mistral:7b など）
• 推奨環境：16GB以上のRAM、CUDA対応GPU（オプションだが推奨）

インストール

# リポジトリをクローン
git clone https://github.com/ardathhomeless585/mini-coding-agent.git
cd mini-coding-agent

# 依存関係をインストール
pip install -r requirements.txt

# 設定ファイルをコピー
cp config.example.yaml config.yaml

設定

config.yaml を編集して、環境に合わせて設定します：

ollama:
  base_url: "http://localhost:11434"  # Ollama サーバーのURL
  model: "codellama:7b"               # 使用するモデル
  temperature: 0.2                     # 生成パラメータ
workspace:
  path: "./workspace"                 # 作業ディレクトリ
  snapshot_enabled: true               # スナップショット機能の有効/無効
memory:
  path: "./memory.json"               # 永続メモリファイルのパス
  enabled: true                        # メモリ機能の有効/無効
approval:
  timeout: 60                          # 承認待機のタイムアウト（秒）
  auto_approve_patterns: []            # 自動承認するツール呼び出しのパターン（例：["read_file"]）

使用方法

エージェントの起動

python run_agent.py --config config.yaml

基本的なワークフロー

1. エージェントがタスクの説明を受け取ります（例：「 src/main.py に新しい関数 greet を追加して」）。
2. エージェントがツール呼び出しを計画します（例： read_file → edit_file）。
3. 各ツール呼び出しが承認キューに表示されます：

   ╔══════════════════════════════════╗
   ║ 承認キュー                       ║
   ╠══════════════════════════════════╣
   ║ ツール: edit_file               ║
   ║ ファイル: src/main.py           ║
   ║ 変更: 関数 `greet` を追加       ║
   ╠══════════════════════════════════╣
   ║ [承認] [拒否] [スナップショット表示] ║
   ╚══════════════════════════════════╝
   

4. ユーザーがアクションを承認（または拒否）します。
5. エージェントがツールを実行し、ワークスペーススナップショットを更新します。
6. 必要に応じて、ユーザーはスナップショットの差分をレビューできます。

スナップショット管理

# 現在のスナップショットを表示
python manage_snapshots.py --show

# 特定のスナップショットとワークスペースの差分を表示
python manage_snapshots.py --diff snapshot_123

# スナップショットからワークスペースを復元
python manage_snapshots.py --restore snapshot_123

メモリ管理

エージェントのメモリは自動的に管理されますが、手動で操作することもできます：

# メモリの内容を表示
python manage_memory.py --show

# メモリをクリア
python manage_memory.py --clear

# メモリにキーと値のペアを追加
python manage_memory.py --add key_name "value"

カスタマイズ

新しいツールの追加

tools/ ディレクトリに新しいPythonファイルを作成し、 Tool ベースクラスを継承します：

from .base import Tool

class MyCustomTool(Tool):
    name = "my_custom_tool"
    description = "カスタムツールの説明"

    def execute(self, params: dict) -> dict:
        # ツールのロジックを実装
        return {"status": "success", "result": ...}

承認ルールの設定

config.yaml で自動承認パターンを設定し、頻繁に使用する安全なツールの承認プロセスをスキップできます：

approval:
  auto_approve_patterns:
    - "read_file"
    - "search_files"

セキュリティに関する考慮事項

• エージェントには、作業ディレクトリへの読み取り/書き込みアクセス権限のみを付与してください。
• 重要なシステムファイルやパスワードなどの機密情報にエージェントがアクセスできないようにしてください。
• 承認キューを定期的に監視し、想定外のツール呼び出しがないか確認してください。
• 未知のモデルを実行する場合は注意してください。モデルによっては悪意のあるコードを生成する可能性があります。

トラブルシューティング

• Ollama に接続できない: Ollama サーバーが実行中で、 base_url が正しいことを確認してください。
• モデルが見つからない: ollama list を実行して、必要なモデルがダウンロードされているか確認してください。
• 承認がタイムアウトする: config.yaml の timeout 値を大きくしてください。
• スナップショットが大きくなりすぎる: 古いスナップショットを定期的に削除するか、スナップショットの保持数を制限するオプションを設定してください。

ライセンス

このプロジェクトは MIT ライセンス の下で提供されています。