diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..9127b22 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,22 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + +jobs: + test: + runs-on: ubuntu-latest + strategy: + matrix: + node: [20, 22] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node }} + cache: npm + - run: npm ci + - run: npm run typecheck + - run: npm test diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..7f22cfa --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,61 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [1.0.0-alpha.0] - 2026-05-11 + +### Added + +- npm 配布対応: `bin/cogsync.js` エントリ追加、`tsx` を runtime 依存へ昇格。 +- README を公開向けに再構成、`cogsync mcp` の登録方法を明示。 +- GitHub Actions CI(Node 20、`typecheck` + `test`)。 +- CHANGELOG / `prepublishOnly` で品質ゲート。 + +### Changed + +- `package.json` から `private: true` を解除。`repository`/`bugs`/`keywords` を追加。 +- CLI バージョン文字列を `0.5.0-alpha.0` → `1.0.0-alpha.0`。 + +## [0.5.0-alpha.0] - 2026-05-09 + +### Added + +- MCP server (`cogsync mcp`) — read-only Resources。Claude Code 等から状態取得。 +- MCP Tools: `set_phase` / `get_recommended_action` / `create_handoff`。 +- MCP Prompts: `coach_phase_transition` / `coach_break_suggestion` ほか。 + +## [0.4.0-alpha.0] + +### Changed + +- UX 磨き — top session の揺らぎ、通知 spam 抑制、phase 失効ロジック。 + +## [0.3.0-alpha.0] + +### Added + +- `work_state` 推定、`DeepWorkAccumulator`、ブレイク提案、適応ポモドーロ。 +- LLM ハンドオフ要約(Ollama)、スキル熟度推定、replay バックテスト。 + +## [0.2.0-alpha.0] + +### Added + +- フェーズ永続化、raw JSONL リーダ、雪だるま検出、`advise`。 +- 通知の WSL → PowerShell トーストフォールバック。 +- ccusage 観測の TTL キャッシュと in-flight dedup。 +- バックテスト: snowball 閾値チューニング(デフォルト 150k)。 + +## [0.1.0-alpha.0] + +### Added + +- 初期 MVP: `ccusage` 経由で 5h ウィンドウ残量を取得、`status` / `watch` を実装。 + +[Unreleased]: https://github.com/akihidem/cogsync-cli/compare/v1.0.0-alpha.0...HEAD +[1.0.0-alpha.0]: https://github.com/akihidem/cogsync-cli/releases/tag/v1.0.0-alpha.0 diff --git a/README.md b/README.md index 4471149..d1e2077 100644 --- a/README.md +++ b/README.md @@ -1,146 +1,83 @@ -# cogsync-cli - -> cogsync MVP 実装:CLI + デスクトップ通知で「AI のリミット回復サイクル」と「人間の集中サイクル」を同期させ、フェーズに応じた指南とタイマー指示を出す。 - -## このリポジトリの位置付け - -| | cogsync (調査) | **cogsync-cli (本リポ)** | -| --- | --- | --- | -| 役割 | 仕様策定・調査・コンセプト設計 | 実装。CLI で動く MVP | -| URL | github.com/akihidem/cogsync | github.com/akihidem/cogsync-cli | -| 状態 | v0.2 予備調査ノート | **v0.0 スケルトン**(責務定義のみ) | -| 公開 | private | private | - -仕様の出典は cogsync 側の以下: - -- [`product/concept.md`](https://github.com/akihidem/cogsync/blob/main/product/concept.md) — コア仮説とストーリーボード -- [`product/requirements.md`](https://github.com/akihidem/cogsync/blob/main/product/requirements.md) — 機能要件 ID(OB-/IN-/CO-/TI-/HO-) -- [`product/mvp-scope.md`](https://github.com/akihidem/cogsync/blob/main/product/mvp-scope.md) — 段階リリース計画 -- [`product/coaching-prompts.md`](https://github.com/akihidem/cogsync/blob/main/product/coaching-prompts.md) — 通知文言テンプレ -- [`product/mcp-server-spec.md`](https://github.com/akihidem/cogsync/blob/main/product/mcp-server-spec.md) — v1.0 で目指す MCP サーバ仕様 - -## MVP(v0.1)スコープ - -| ID | 機能 | 状態 | -| --- | --- | --- | -| OB-1 | ccusage から 5h ブロック取得 | ✅ 子プロセス呼出 + TTL キャッシュ | -| OB-2 | 5h ウィンドウ残量と終了時刻予測 | ✅ | -| IN-2 | 雪だるま効果検出 | ✅ raw JSONL 走査、デフォ閾値 150k | -| IN-3 | リミット枯渇までの予測 | ✅ | -| IN-4 | スキル熟度推定 | ✅ `cogsync skill` コマンド (過去 30 日の並列稼働分布から p90) | -| IN-5 | ディープワーク累積追跡 | ✅ DeepWorkAccumulator、watch で当日累積 | -| CO-1 | フェーズ別モデル提案 | ✅ | -| CO-3 | フェーズ移行時のハンドオフ・プロンプト生成 | ✅ | -| CO-4 | リミット接近通知 | ✅ | -| CO-5 | AI 処理中のディープ・ブレイク提案 | ✅ ai_busy 5 分超で `deep_break_suggested` | -| TI-1 | 適応的ポモドーロ(AI 処理時間で動的伸縮) | ✅ `cogsync pomodoro start` | -| HO-1 | ハンドオフ・プロンプトのテンプレ提供 | ✅ + `--llm` で Ollama 自動要約 | -| HO-2 | クリップボード | ✅ clip.exe/wl-copy/xclip/pbcopy フォールバック | -| HO-4 | MCP サーバ化 | 未着手 (v1.0) | - -`docs/DESIGN.md` に内部設計、`src/` に責務スケルトンを配置済み。 - -## 技術スタック - -| 層 | 採用 | 理由 | -| --- | --- | --- | -| ランタイム | Node.js 20+ | 既存環境で即動く。Bun への移行は v0.2 以降の検討事項 | -| TS 実行 | tsx 4 | 開発時は `npx tsx src/index.ts` で起動、ビルド不要 | -| 言語 | TypeScript(厳格モード) | ccusage / MCP SDK との親和性 | -| ストレージ | better-sqlite3 | 同期 API、依存少、組み込み(v0.2 で導入) | -| ファイル監視 | chokidar | クロスプラットフォーム(v0.2 で導入) | -| 通知 | node-notifier | macOS / Linux / Windows(v0.1 で導入) | -| 設定 | YAML(`js-yaml`) | 編集容易、コメント可 | -| MCP(v1.0) | `@modelcontextprotocol/sdk` | 公式 | - -→ MVP は **CLI のみ・GUI なし**。GUI(Tauri)は MVP の有用性が確認できた v0.2 以降。 -→ v0.1 は ccusage 子プロセス呼び出しのため、依存は最小(commander + js-yaml)。SQLite / 通知 / 監視は機能を追加する v0.2 以降に依存追加する。 - -## ディレクトリ構成 +# cogsync -``` -cogsync-cli/ -├── README.md # 本ファイル -├── package.json -├── tsconfig.json -├── docs/ -│ ├── DESIGN.md # 内部設計とデータフロー -│ └── ROADMAP.md # MVP → v1.0 の段階計画 -├── src/ -│ ├── index.ts # CLI エントリ(コマンド定義) -│ ├── config.ts # 設定ファイル読み込み -│ ├── observers/ # 観測層(OB-*) -│ │ ├── ccusage.ts -│ │ └── claude_code.ts -│ ├── infer/ # 推論層(IN-*) -│ │ ├── window5h.ts -│ │ ├── snowball.ts -│ │ └── deepwork.ts -│ ├── coach/ # 指南層(CO-*) -│ │ ├── phase.ts -│ │ └── advise.ts -│ ├── timer/ # タイマー(TI-*) -│ │ └── adaptive.ts -│ ├── handoff/ # ハンドオフ(HO-*) -│ │ └── template.ts -│ ├── notify/ # OS 通知 -│ │ └── desktop.ts -│ └── state/ # 永続化 -│ └── store.ts -└── tests/ # 後で +> AI のリミット回復サイクル(Claude Code の 5h ブロック)と人間の集中サイクルを同期させる CLI コーチ。CLI と MCP サーバの両方で動作する。 + +[![CI](https://github.com/akihidem/cogsync-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/akihidem/cogsync-cli/actions/workflows/ci.yml) +[![npm](https://img.shields.io/npm/v/cogsync-cli/alpha.svg)](https://www.npmjs.com/package/cogsync-cli) +[![license](https://img.shields.io/npm/l/cogsync-cli.svg)](./LICENSE) + +## 何をするか + +Claude Code を長時間使う日、5h リミットの残量・雪だるま化したセッション・ディープワーク累積を観測して、フェーズに応じた指南(design / implement / review / break)と適応ポモドーロを出す。MCP サーバとしても起動でき、Claude Code 側から直接フェーズ切替・ハンドオフ生成ができる。 + +- **観測**: `ccusage` の 5h ブロック + Claude Code raw JSONL を継続ポーリング +- **推論**: 残量・枯渇予測・雪だるま検出・並列稼働分布から推奨フェーズを決定 +- **指南**: デスクトップ通知(macOS / Linux / Windows / WSL→PowerShell トースト) +- **タイマー**: 適応ポモドーロ(AI 処理時間に応じて伸縮) +- **ハンドオフ**: フェーズ移行時のプロンプト雛形をクリップボードへ +- **MCP**: stdio で Resources / Tools / Prompts を Claude Code に公開 + +## 必要環境 + +- Node.js 20+ +- [`ccusage`](https://github.com/ryoppippi/ccusage) が `npx ccusage` で呼べる状態(Claude Code 利用者ならまず入っている) + +## インストール + +```bash +# グローバルインストール(α 版) +npm install -g cogsync-cli@alpha + +# または npx +npx cogsync-cli@alpha status ``` -## 起動コマンド +## クイックスタート ```bash -npm install # 依存インストール -npm run status # 現在の 5h ウィンドウ残量を 1 行表示 -npm run status -- --json # JSON 出力(プログラム消費用) -npm run watch # 常駐モード(ポーリング+通知) -npx tsx src/index.ts watch --once # 動作確認用ワンショット -npx tsx src/index.ts config # 解決後の設定を表示 -npx tsx src/index.ts handoff --goal ... --state ... --next ... # ハンドオフ生成+クリップボード -npx tsx src/index.ts handoff --llm # 現セッションを Ollama (gemma4) で自動要約 -npx tsx src/index.ts skill # 過去 30 日から並列稼働数を推定 -npx tsx scripts/backtest-window5h.ts # 過去 5h ブロックの集計レポート -npx tsx scripts/backtest-snowball.ts # 雪だるま閾値の発火頻度 -npx tsx scripts/backtest-replay.ts --limit 20 # 時系列バックテスト -npx tsx src/index.ts phase set design # フェーズ手動切替 -npx tsx src/index.ts pomodoro start --focus 25 --break 5 --cycles 4 # 適応的ポモドーロ +cogsync status # 現在の 5h ウィンドウ残量を 1 行表示 +cogsync status --json # JSON 出力(他プログラムから消費) +cogsync watch # 常駐モード。閾値超えで OS 通知 +cogsync phase set design # 手動フェーズ切替 +cogsync pomodoro start # 適応ポモドーロ +cogsync handoff --title 認証 --goal "JWT を分離" --next "Cookie 経路を extract" +cogsync mcp # MCP サーバ起動(stdio) ``` -### 実出力例 +実行例: ```text -$ npm run status +$ cogsync status Claude 5h ウィンドウ | 残り 4h16m | (終了 17:00) | 累計 2.81M | 8,636 tok/min ``` `残り` は **5h ウィンドウ終了時刻** と **現バーンレート想定の枯渇予測時刻** の早い方を採用。 -枯渇予測が先に来た場合は `(枯渇予測 HH:MM - 現バーンレート想定)` と表示される。 +枯渇予測が先に来た場合は `(枯渇予測 HH:MM - 現バーンレート想定)` を表示する。 -```text -$ npx tsx src/index.ts watch --once -[12:48:30] Claude 5h ウィンドウ | 残り 4h11m | (終了 17:00) | 累計 13.34M | 9,916 tok/min -``` +## MCP サーバとして使う -```text -$ npx tsx src/index.ts handoff --title 認証 --goal "JWT を分離" --state "extract 済み" --next "Cookie 経路を extract" --decision "JWT は別 MW" -# Handoff: 認証 -- Goal: JWT を分離 -- State: extract 済み -- Decisions: - - JWT は別 MW -- Open Questions: - (none) -- Next Action: Cookie 経路を extract -[Created by cogsync at 2026-04-30T...] -[cogsync] copied to clipboard via clip.exe +Claude Code の `~/.claude/settings.json` などに登録: + +```json +{ + "mcpServers": { + "cogsync": { + "command": "cogsync", + "args": ["mcp"] + } + } +} ``` -### 設定 +提供する Resource / Tool / Prompt の一覧は [`docs/MCP.md`](./docs/MCP.md) 参照。代表的なものは: + +- Resource: `cogsync://state/window5h`, `cogsync://state/phase`, `cogsync://state/deepwork` +- Tool: `set_phase`, `get_recommended_action`, `create_handoff` +- Prompt: `coach_phase_transition`, `coach_break_suggestion` -`~/.config/cogsync/config.yaml` で上書き可能。`--config ` または環境変数 `COGSYNC_CONFIG` でも上書き。 +## 設定 + +`~/.config/cogsync/config.yaml` で上書き可能(`--config ` / `COGSYNC_CONFIG` 環境変数でも可)。 ```yaml profile: @@ -158,10 +95,55 @@ observers: pollingSec: 30 ``` -## ライセンス +## 主なコマンド + +| コマンド | 役割 | +| --- | --- | +| `cogsync status [--json]` | 5h ウィンドウ残量を 1 行表示 | +| `cogsync watch [--once]` | 常駐ポーリング・通知 | +| `cogsync phase set ` | フェーズ手動切替 | +| `cogsync phase get` | 現フェーズ表示 | +| `cogsync pomodoro start [--focus 25] [--break 5] [--cycles 4] [--no-adaptive]` | 適応ポモドーロ | +| `cogsync handoff [--title] [--goal] [--state] [--next] [--llm]` | ハンドオフ雛形を生成・クリップボード | +| `cogsync skill` | 過去 30 日の並列稼働分布から熟度を推定 | +| `cogsync config` | 解決後の設定をダンプ | +| `cogsync mcp` | MCP stdio サーバ起動 | + +`--help` で詳細オプションを表示。 + +## アーキテクチャ + +``` +src/ +├── index.ts # CLI エントリ +├── config.ts # 設定読み込み +├── observers/ # 観測層(ccusage / claude_code raw JSONL) +├── infer/ # 推論層(window5h / snowball / deepwork) +├── coach/ # 指南層(phase / advise) +├── timer/ # 適応ポモドーロ +├── handoff/ # ハンドオフ雛形 + Ollama 要約 +├── notify/ # OS 通知(WSL→PowerShell トースト含む) +├── state/ # フェーズ・累積の永続化 +└── mcp/ # MCP server (resources / tools / prompts) +``` -MIT を予定(v1.0 公開時に確定)。 +詳細は [`docs/DESIGN.md`](./docs/DESIGN.md) / [`docs/ROADMAP.md`](./docs/ROADMAP.md)。 + +## 開発 + +```bash +git clone https://github.com/akihidem/cogsync-cli.git +cd cogsync-cli +npm install +npm run typecheck +npm test +npm run dev -- status # tsx 経由でローカル実行 +``` ## ステータス -**v0.3.0-alpha.0**:MVP 全コマンドが動作。watch は ccusage 5h ブロック観測 + raw JSONL 雪だるま検出 + AI 処理状態判定 (active/ai_busy/idle) + DeepWorkAccumulator + advise + WSL→PowerShell トースト + TTL キャッシュ統合済み。`pomodoro start` で適応ポモドーロ、`skill` でスキル熟度推定、`handoff --llm` で Ollama 自動要約、`scripts/backtest-replay.ts` で時系列バックテスト。MCP サーバ化は v1.0。 +`v1.0.0-alpha`: CLI 全コマンド + MCP Resources / Tools / Prompts が動作。安定版(v1.0.0)は実利用フィードバックを経て確定する。 + +## ライセンス + +[MIT](./LICENSE) diff --git a/bin/cogsync.js b/bin/cogsync.js new file mode 100755 index 0000000..a00cdef --- /dev/null +++ b/bin/cogsync.js @@ -0,0 +1,11 @@ +#!/usr/bin/env node +// cogsync CLI entrypoint. +// tsx の tsImport API で src/index.ts を直接ロードする(ビルドステップなし)。 +import { tsImport } from "tsx/esm/api"; +import path from "node:path"; +import { pathToFileURL, fileURLToPath } from "node:url"; + +const here = path.dirname(fileURLToPath(import.meta.url)); +const entry = path.resolve(here, "..", "src", "index.ts"); + +await tsImport(pathToFileURL(entry).href, import.meta.url); diff --git a/package.json b/package.json index e457e6e..c5bc6a6 100644 --- a/package.json +++ b/package.json @@ -1,34 +1,64 @@ { "name": "cogsync-cli", "version": "1.0.0-alpha.0", - "description": "AI のリミット回復サイクルと人間の集中サイクルを同期させる CLI コーチ", + "description": "AI のリミット回復サイクル(5h ブロック)と人間の集中サイクルを同期させる CLI コーチ。MCP サーバとしても動作。", "type": "module", - "private": true, "bin": { "cogsync": "./bin/cogsync.js" }, + "files": [ + "bin", + "src", + "scripts", + "tsconfig.json", + "README.md", + "CHANGELOG.md", + "LICENSE" + ], "scripts": { "dev": "tsx src/index.ts", "status": "tsx src/index.ts status", "watch": "tsx src/index.ts watch", "test": "node --test --import tsx/esm tests/*.test.ts", - "typecheck": "tsc --noEmit" + "typecheck": "tsc --noEmit", + "prepublishOnly": "npm run typecheck && npm test" }, "engines": { "node": ">=20.0.0" }, + "keywords": [ + "claude-code", + "claude", + "ccusage", + "mcp", + "pomodoro", + "deep-work", + "rate-limit", + "coach", + "cli" + ], + "author": "akihidem", + "license": "MIT", + "homepage": "https://github.com/akihidem/cogsync-cli#readme", + "repository": { + "type": "git", + "url": "git+https://github.com/akihidem/cogsync-cli.git" + }, + "bugs": { + "url": "https://github.com/akihidem/cogsync-cli/issues" + }, "dependencies": { "@modelcontextprotocol/sdk": "^1.29.0", "@types/node-notifier": "^8.0.5", "chokidar": "^5.0.0", "commander": "^12.0.0", "js-yaml": "^4.1.0", - "node-notifier": "^10.0.1" + "node-notifier": "^10.0.1", + "tsx": "^4.19.0" }, "devDependencies": { "@types/js-yaml": "^4.0.9", "@types/node": "^22.0.0", - "tsx": "^4.19.0", "typescript": "^5.6.0" } } diff --git a/src/index.ts b/src/index.ts index ed9ca49..0e51841 100644 --- a/src/index.ts +++ b/src/index.ts @@ -21,7 +21,7 @@ const program = new Command(); program .name("cogsync") .description("AI のリミット回復サイクルと人間の集中サイクルを同期させる CLI コーチ") - .version("0.5.0-alpha.0") + .version("1.0.0-alpha.0") .option("--config ", "設定ファイルパス(既定 ~/.config/cogsync/config.yaml、env COGSYNC_CONFIG でも上書き)"); program