Deskmate

🚀 デスクメイト

自然言語を使ってどこからでもローカルマシンを制御できます。

Deskmateは、自然言語を使って個人のマシンを制御でき、既に使用しているチャンネルで会話するローカル実行エージェントです。Deskmateは、自律性やオーケストレーションではなく、実行に焦点を当てています。携帯電話からTelegramメッセージを送信すると、マシン上で実行されます。複数のエージェントバックエンド — Claude Code、Codex (OpenAI)、Gemini CLI、および OpenCode — をサポートし、完全なローカルツールアクセスが可能で、サンドボックス化されたコマンドセットや人工的な制限はありません。

このプロジェクトは、机の前にいなくても創造的な開発の流れを維持するという単純な目標から生まれた情熱的なプロジェクトです。gen-shellに触発されて開発されました。

はじめる · ゲートウェイモード · エージェントプロバイダー · アーキテクチャ · Discord

🎬 デモ

🔍 仕組み

Telegram / Discord* / Slack* / ...
            |
            v
  +-------------------+
  |      ゲートウェイ      |    認証、セッション、承認ルーティング
  |  (制御プレーン)  |
  +--------+----------+
           |
           v
  +-------------------+
  |   エージェントプロバイダー  |    Claude Code | Codex | Gemini | OpenCode
  |   (プラガブル)     |    完全なローカルツールアクセス
  +-------------------+
           |
           v
     あなたのマシン
     (タスクを実行)

*DiscordとSlackのアダプターは計画中です — 新しいクライアントの追加を参照してください。

ゲートウェイは制御プレーンです。各メッセージングプラットフォームは薄い入出力アダプターです。エージェントは、保護されたフォルダに対するオプションの承認ゲート付きで、あなたのマシンに無制限にアクセスできます（デフォルトで承認）。

📋 責任範囲

Deskmateの責任は 実行 です。

• 意図を具体的なシステムアクションに変換します
• 他のエージェントを調整しません

✨ 主な機能

• 完全なローカルアクセス — エージェントは任意のコマンドを実行し、任意のファイルを読み書きし、スクリーンショットを撮ることができます。6つのツールのサンドボックスなどの人工的な制限はありません。
• マルチチャネルゲートウェイ — 現在はTelegram、将来的にはDiscord/Slack/WhatsAppをサポートします。1つのゲートウェイで複数のクライアントを扱えます。
• 会話メモリ — メッセージ間でセッションの継続性があります。自然にフォローアップの質問をすることができます。
• マルチエージェントバックエンド — Claude Code（デフォルト）、Codex (OpenAI)、Gemini CLI (Google)、およびOpenCodeが搭載されています。.env で AGENT_PROVIDER=codex などと設定することで切り替えられます。
• デフォルトで承認 — 安全なコマンドは自動承認されます。保護されたフォルダ（デスクトップ、ドキュメントなど）については、インラインボタンを介して確認を求められます。
• MCPサーバー — あなたのマシンをClaude Desktopまたは任意のMCPクライアント用のツールサーバーとして公開します。
• スキルシステム — skills.json で再利用可能な多段階ワークフローを定義できます。スキルはコマンド、エージェントプロンプト、または他のスキルを実行できます。ファイルが変更されるとホットリロードされます。
• クロンスケジューラー — crons.json を介して定期的なジョブ（コマンド、エージェントクエリ、またはスキル）をスケジュールできます。結果はアクティブなチャットチャネルに送信されます。
• ヘルスモニタリング — CPU、メモリ、ディスク、エージェントの可用性に関するビルトインのヘルスチェックがあります。Telegramで /health、CLIで deskmate health、または get_health MCPツールを使用してアクセスできます。
• Dockerコンテナモード — ホストコマンド用のネイティブサイドカーとともに、コアをDockerで実行できます。INSTALL_MODE=container を設定し、docker-compose up を使用します。
• サービスとして実行 — launchd (macOS) またはsystemd (Linux) と統合され、起動時に自動起動し、クラッシュ時に自動再起動します。
• 拡張可能なエージェントレイヤー — registerProvider() を介して独自のエージェントを導入できます。

📋 必要条件

• macOS (Ventura、Sonoma、Sequoiaでテスト済み) または Linux (systemd付き)
• WSL2 を介したWindows
• Node.js 18以上
• サポートされているエージェントCLIのいずれかがインストールされていること ( エージェントプロバイダー を参照)
• Telegramアカウント (Telegramモードの場合)
• 選択したプロバイダーのAPIキー (Anthropic、OpenAI、またはGoogle — OpenCodeは独自の認証を管理)

Linuxの前提条件

• スクリーンショット：スクリーンショットをサポートするには ImageMagick をインストールしてください (sudo apt install imagemagick)
• サービス：ユーザーセッションをサポートするsystemd (systemctl --user)

macOSのパーミッション

インストーラーがこれらの手順を案内します（macOSのみ）。手動で システム設定 > プライバシーとセキュリティ で設定することもできます。

🚀 クイックスタート

オプションA: npmからインストール (推奨)

npm install -g @sarkar-ai/deskmate
deskmate init

ウィザードがAPIキー、Telegram資格情報、プラットフォームパーミッション、およびバックグラウンドサービスの設定を案内します。設定は ~/.config/deskmate/.env に保存されます。

設定後、deskmate で手動で実行するか、バックグラウンドサービスに任せることができます。

オプションB: ソースからインストール (コントリビューター向け)

git clone https://github.com/sarkar-ai-taken/deskmate.git
cd deskmate
npm install --legacy-peer-deps
npm run build
./install.sh          # 対話式: .env、サービス、パーミッションを設定

または、シェルインストーラーの代わりにTypeScriptウィザードを使用します。

cp .env.example .env  # 資格情報を編集
npx deskmate init     # または: npm link && deskmate init

後で再設定するには deskmate init を実行します。

🎛️ 実行モード

注意: deskmate telegram も動作しますが、ゲートウェイを起動する非推奨のエイリアスです。

🌐 ゲートウェイモード

ゲートウェイはDeskmateを実行するデフォルトの方法です。プラットフォームの入出力をエージェントロジックから分離するため、新しいメッセージングクライアントを追加する際に認証、セッション、またはエージェントレイヤーに触れる必要はありません。

# マルチクライアント認証を設定
ALLOWED_USERS=telegram:123456,discord:987654321

# 起動
deskmate

ゲートウェイは、利用可能な環境変数に基づいてクライアントを自動登録します。TELEGRAM_BOT_TOKEN が設定されている場合、Telegramがアクティブになります。将来のクライアント（Discord、Slack）も同じパターンに従います。

🤖 ボットコマンド

💻 使用例

基本的な使用法

# システム管理
"ディスク使用量を表示", "最も多くのCPUを使用しているプロセスは何か?", "すべての実行中のDockerコンテナを一覧表示"

# ファイル操作
"package.jsonの内容を表示", "src/内のすべてのTypeScriptファイルを検索", "今日の日付でnotes.txtという新しいファイルを作成"

# 開発
"テストを実行", "gitのステータスは?", "最近のコミットを表示"

# トラブルシューティング
"ポート8080を使用しているものは何か?", "エラーログの最後の50行を表示", "nginxが実行中か確認"

# 視覚的な操作
"スクリーンショットを撮る", "画面に表示されているものを表示"

🖥️ MCPサーバー

MCPサーバーは、あなたのマシンをClaude Desktopまたは任意のMCPクライアント用のツールサーバーとして公開します。

Claude Desktopでのセットアップ

~/Library/Application Support/Claude/claude_desktop_config.json に以下を追加します。

{
  "mcpServers": {
    "deskmate": {
      "command": "node",
      "args": ["/path/to/deskmate/dist/index.js", "mcp"],
      "env": {
        "WORKING_DIR": "/Users/yourname"
      }
    }
  }
}

Claude Desktopを再起動します。これでClaudeにローカルマシンとの対話を依頼することができます。

結合モード (ゲートウェイ + MCP)

deskmate both で両方を実行します。MCPはClaude Desktopのリクエストを処理し、ゲートウェイはTelegram（および将来のクライアント）を処理し、機密操作の承認通知を携帯電話に送信するため、どこからでも承認できます。

可観測性

Deskmateは、アクションを安全に実行することに焦点を当てています。

複数のローカルエージェント間でエージェントの動作、リソース使用量、および障害を監視するには、Riva（ローカルファーストのエージェント可観測性）を参照してください。

🛠️ スキル

スキルは、JSONで定義された再利用可能な多段階ワークフローです。skills.json をプロジェクトルートまたは ~/.config/deskmate/skills.json に配置すると、グローバルなスキルになります。ファイルが変更されると、スキルはホットリロードされます。

{
  "version": 1,
  "skills": [
    {
      "name": "deploy",
      "description": "プロジェクトをビルドしてデプロイする",
      "parameters": [{ "name": "env", "required": true }],
      "steps": [
        { "type": "command", "command": "npm run build" },
        { "type": "command", "command": "./deploy.sh {{env}}" }
      ]
    }
  ]
}

各ステップは command（シェル）、prompt（エージェントクエリ）、または skill（ネストされたスキル）にすることができます。Telegramで /skill deploy env=staging または run_skill MCPツールで実行します。

⏰ クロンジョブ

crons.json（プロジェクトローカルまたは ~/.config/deskmate/crons.json）を介して定期的なジョブをスケジュールします。

{
  "version": 1,
  "jobs": [
    {
      "name": "daily-backup",
      "schedule": "0 2 * * *",
      "action": { "type": "command", "command": "tar czf ~/backup.tar.gz ~/Documents" },
      "notify": true
    }
  ]
}

アクションは command、agent_query（自然言語プロンプト）、または skill にすることができます。notify: true を設定すると、アクティブなチャットチャネルに結果が送信されます。Telegramで /cron または list_cron_jobs MCPツールでステータスを確認します。

🔒 セキュリティ

⚠️ 重要: エージェントはあなたのマシン上で任意のコマンドを実行できます。これは設計上のもので、読み取り専用操作についてはデフォルトで承認し、保護されたフォルダや書き込み操作については承認ゲートを設けています。

ビルトインの保護機能

承認ワークフロー

1. ユーザーが機密操作をトリガーするメッセージを送信する（例：~/Documents に書き込む）
2. ApprovalManager がアクションが安全な自動承認パターンに一致するかどうかを確認する
3. 安全でない場合、タイムアウトカウントダウン付きの保留中の承認が作成される
4. 承認要求が最近アクティブなすべてのクライアント（過去30分以内）にブロードキャストされる
5. ユーザーがインラインボタン（Telegram）または同等のものを介して承認/拒否をタップする
6. 承認された場合はアクションが実行され、拒否またはタイムアウトした場合はキャンセルされる

REQUIRE_APPROVAL_FOR_ALL=true を設定すると、読み取り操作を含むすべての操作に承認が必要になります。

推奨事項

• WORKING_DIR を設定して、デフォルトのコマンド範囲を制限する
• ALLOWED_USERS を使用してマルチクライアントの許可リストを設定する
• ALLOWED_FOLDERS を使用して特定のディレクトリを事前承認する
• 定期的にログを確認する (logs/stdout.log)
• .env を安全に保管し、決してコミットしない
• すべての操作を承認したい場合は REQUIRE_APPROVAL_FOR_ALL=true を使用する

実行哲学

Deskmateは デフォルトで承認、明示的な設計 のモデルに従います。

• 読み取り専用操作は自動承認されます
• 機密操作には明示的な確認が必要です
• すべてのアクションはローカルにログに記録されます

目標は、隠れた動作なしで高速な実行です。

❌ 非目標

Deskmateは意図的に以下のものではありません。

• マルチエージェントオーケストレーションフレームワーク
• クラウドホスト型の制御プレーン
• 長時間実行される自律システム

これらの制約は意図的なものです。

🤖 エージェントプロバイダー

Deskmateは複数のエージェントバックエンドをサポートしています。.env で AGENT_PROVIDER を設定するか、deskmate init 中に選択します。

# プロバイダーを切り替える
AGENT_PROVIDER=codex
OPENAI_API_KEY=sk-...

# またはウィザードを使用する
deskmate init

選択したプロバイダーに一致するAPIキーのみが必要です。他のプロバイダーのキーは、切り替えた後に .env に保存されます。

🏗️ アーキテクチャ

src/
├── core/
│   ├── agent/
│   │   ├── types.ts              # AgentProviderインターフェース
│   │   ├── factory.ts            # プロバイダーファクトリ + registerProvider()
│   │   └── providers/
│   │       ├── claude-code.ts    # Claude Code SDK (デフォルト)
│   │       ├── base-cli.ts       # CLIで起動されるプロバイダーのベースクラス
│   │       ├── codex.ts          # Codex (OpenAI)
│   │       ├── gemini.ts         # Gemini CLI (Google)
│   │       └── opencode.ts       # OpenCode
│   ├── approval.ts               # 承認マネージャー (自動承認 + 手動)
│   ├── executor.ts               # コマンド実行、ファイル入出力、スクリーンショット
│   ├── executor-factory.ts       # ローカルまたはリモートエグゼキューターを作成
│   ├── executor-interface.ts     # IExecutorインターフェース
│   ├── remote-executor.ts        # サイドカーに委譲するエグゼキューター
│   ├── health.ts                 # ヘルスモニタリング (CPU、メモリ、ディスク、エージェント)
│   ├── skills/                   # スキルシステム
│   │   ├── types.ts              # スキル定義スキーマ (Zod)
│   │   ├── registry.ts           # skills.jsonを読み込み、変更時にホットリロード
│   │   └── executor.ts           # 多段階スキルワークフローを実行
│   ├── cron/                     # クロンスケジューラー
│   │   ├── types.ts              # クロンジョブ定義スキーマ (Zod)
│   │   └── scheduler.ts          # node-cronベースのジョブランナー
│   └── logger.ts                 # 構造化ロギング
├── gateway/
│   ├── types.ts                  # MessagingClient、MessageHandlerインターフェース
│   ├── gateway.ts                # 中央コーディネーター
│   ├── security.ts               # マルチクライアント許可リスト認証
│   └── session.ts                # セッションマネージャー (複合キー、アイドル削除)
├── clients/
│   └── telegram.ts               # Telegramアダプター (grammY)
├── sidecar/                      # コンテナモード用のホストサイドカー
│   ├── server.ts                 # HTTPを介してエグゼキューターを公開するExpressサーバー
│   └── cli.ts                    # サイドカーCLIエントリポイント
└── mcp/
    └── server.ts                 # MCPサーバー

エージェントレイヤー — 4つのプロバイダーが搭載されています：Claude Code（@anthropic-ai/claude-agent-sdk を介して）、Codex、Gemini CLI、およびOpenCode。Claude以外の3つのプロバイダーは BaseCliProvider を拡張しており、サブプロセスの起動と標準出力のストリーミングを処理します。カスタムエージェントプロバイダーは registerProvider() を介して登録できます。

ゲートウェイレイヤー — 認証 (SecurityManager)、セッション (SessionManager)、エージェントオーケストレーション、承認ルーティング、およびスクリーンショット配信を処理する中央コーディネーターです。プラットフォームアダプターは MessagingClient インターフェースを実装し、入出力のみを行います。

新しいクライアントの追加

1. src/clients/discord.ts を作成し、MessagingClient を実装します（src/gateway/types.ts を参照）
2. .env に DISCORD_BOT_TOKEN を追加します
3. ALLOWED_USERS に discord:userId を追加します
4. ゲートウェイの起動時に登録します: gateway.registerClient(new DiscordClient(token))

ゲートウェイ、SecurityManager、SessionManager、またはエージェントレイヤーに変更は必要ありません。

独自のエージェントを導入する

import { AgentProvider, registerProvider } from "./core/agent";

class MyAgent implements AgentProvider {
  readonly name = "my-agent";
  readonly version = "1.0.0";
  // query(), queryStream(), isAvailable() を実装
}

registerProvider("my-agent", MyAgent);
// 次に .env で AGENT_PROVIDER=my-agent を設定

💻 CLIコマンド

🐳 Docker / コンテナモード

DeskmateをDockerコンテナで実行し、ネイティブサイドカーでホストレベルのコマンド（スクリーンショット、ファイルアクセス）を処理します。

# インストールモードを設定
INSTALL_MODE=container

# ホストでサイドカーを起動
deskmate sidecar

# コンテナを起動
docker-compose up -d

Dockerfile と docker-compose.yml はパッケージに含まれています。サイドカーはローカルHTTP APIを公開し、コンテナ化されたコアがホスト上でコマンドを実行するために使用します。

🛠️ サービス管理

macOS (launchd)

# ログを表示
tail -f logs/stdout.log
tail -f logs/stderr.log

# サービスを停止
launchctl unload ~/Library/LaunchAgents/com.deskmate.service.plist

# サービスを起動
launchctl load ~/Library/LaunchAgents/com.deskmate.service.plist

# ステータスを確認
launchctl list | grep deskmate

Linux (systemd)

# ログを表示
tail -f logs/stdout.log
journalctl --user -u deskmate.service -f

# 停止 / 起動 / 再起動
systemctl --user stop deskmate.service
systemctl --user start deskmate.service
systemctl --user restart deskmate.service

# ステータスを確認
systemctl --user status deskmate.service

アンインストール

./uninstall.sh

🐞 トラブルシューティング

ボットが応答しない場合

1. ログを確認します: tail -f logs/stderr.log
2. ALLOWED_USERS にTelegram IDが含まれていることを確認します（例: telegram:123456）
3. エージェントCLIがインストールされていることを確認します（例: which claude, which codex, which gemini, which opencode）
4. deskmate doctor を実行して設定問題を診断します

コマンドがタイムアウトする場合

• デフォルトのタイムアウトは2分です
• 長時間実行されるコマンドは調整が必要かもしれません

マシンがスリープする場合

• macOS: ./install.sh を実行してスリープ防止を設定するか、手動で sudo pmset -c sleep 0 を実行します
• Linux: systemdサービスはアイドルインヒビターを使用します。デスクトップ環境の電源設定を確認してください

パーミッション拒否エラーが発生する場合 (macOS)

• ./install.sh を再実行してパーミッションの設定をやり直します
• または、システム設定 > プライバシーとセキュリティで手動でパーミッションを付与します

スクリーンショットが機能しない場合

• macOS: システム設定 > プライバシーとセキュリティ > 画面録画で画面録画パーミッションを付与します
• Linux: ImageMagickをインストールします (sudo apt install imagemagick)
• 変更を加えた後、サービスを再起動します

🚀 将来の予定 / 協力募集

追加のメッセージングクライアント — ゲートウェイアーキテクチャは準備ができています。以下の追加を歓迎します。

• discord — discord.jsを介したDiscordボット
• slack — Bolt SDKを介したSlackアプリ
• whatsapp — ビジネスAPIを介したWhatsApp

バックグラウンドジョブの処理 — 現在の launchd (macOS) + systemd (Linux) のアプローチは機能しますが、異なるデバイスタイプ（常時オンのMac MiniとMacBook、ヘッドレスLinuxサーバー）に対して改善することができます。

アプローチについて議論するには、イシューを開いてください。

🤝 コントリビュート

コントリビューションを歓迎します！ガイドラインについては CONTRIBUTING.md を参照してください。

アーキテクチャの詳細とローカルセットアップについては DEVELOPMENT.md を参照してください。

📄 ライセンス

MITライセンス — 詳細については LICENSE を参照してください。

🙏 謝辞

• Claude Agent SDK — デフォルトのエージェントランタイム
• Codex — OpenAIエージェントバックエンド
• Gemini CLI — Googleエージェントバックエンド
• OpenCode — OpenCodeエージェントバックエンド
• grammY — Telegramボットフレームワーク
• @modelcontextprotocol/sdk — MCPサポート

👥 コミュニティ

• Discord — コミュニティに参加し、質問をし、あなたのセットアップを共有しましょう

🔗 共有

Deskmateが役に立った場合は、自由に共有してください。

• Xで共有
• Hacker Newsに投稿