Pulse

Pulse は、複数の AI coding agent と協調するための個人開発者向け shared state CLI です。

人間が毎回 chat history を開かなくても、SQLite に保存された Goal / Task / Status / Context / Claim / Heartbeat / Worktree / Branch を見れば、今どの agent が何をしているかを把握できる状態を目指します。

技術方針

この repo は TypeScript で進めます。

理由:

• ユーザーの学習優先度が TypeScript にある
• CLI、状態モデル、SQLite adapter、test harness が TypeScript 学習に向いている
• Node 24 LTS の node:sqlite により、外部 SQLite driver なしで実装できる
• npm run verify に型検査、100% coverage gate、build を集約でき、複利的に育つ harness にしやすい

トレードオフ:

• Node 24.15 以降の node:sqlite はStability 1.2（Release candidate）であり、まだStableではない
• Python は SQLite が標準で安定しており、配布容易性だけを見ると今も強い
• SQLite API は storage adapter 内へ限定し、Node LTS 更新時に互換性を検証する

TypeScript、SQLite、raw SQLは維持し、validation、CLI、HTTP、UIは責務境界を作ってから段階導入します。選定理由と導入条件はADR 0001を参照してください。

Requirements

• Node.js >=24.15.0 <25
• 推奨・CI固定version: .tool-versions
• npm

設計と保守の入口

実装前に次を参照してください。

• Architecture: 現在と目標の依存方向、維持する不変条件
• Domain model: status、Goal、event、競合制御の現行契約
• Database and migrations: schema変更前の必須条件
• ADR 0001: library比較と段階導入方針
• Contributing: 変更種別ごとの手順とverify gate

Install

asdf install
npm ci

asdf以外のversion managerを使う場合も、.tool-versionsと同じNode.jsを選択してからinstallしてください。

Local Command Setup

pulse add や pulse release のように通常の command として実行する場合は、build して local link を作成します。

npm run link:local

これにより、この package の bin.pulse が global npm prefix に link され、同梱の Codex skill も ${CODEX_HOME:-~/.codex}/skills/pulse-shared-state に install されます。CLI link を解除する場合は以下を実行します。

asdfのglobal npm linkはNode versionごとです。Node 24.18.0をinstallした後はnpm run link:localを再実行してください。別repoがNode 22や25を選択している状態では、asdf shimがNo executable pulse found for current versionを返す場合があります。Node versionに依存しないlauncherは未実装のため、現時点ではPulseをlinkしたNode versionを選んで実行します。

npm unlink -g pulse-shared-state

Codex skill は上記では削除されません。不要になった場合は ${CODEX_HOME:-~/.codex}/skills/pulse-shared-state を削除してください。

skill だけを install する場合は以下を実行します。

npm run install:skill

install 先を明示する場合は --skills-dir を指定します。

npm run install:skill -- --skills-dir /path/to/codex/skills

Verify

npm run verify

verify は以下を実行します。

• npm run typecheck
• npm run coverage
• npm run build

CIは公称minimumのNode 24.15.0と、.tool-versionsで固定するNode 24.18.0の両方で同じcommandを実行します。

coverage は Node.js 標準 test runner の coverage gate を使い、src/bin.ts を除く TypeScript source に対して line / function / branch すべて 100% を要求します。src/bin.ts は process exit と標準入出力を接続するだけの薄い executable wrapper です。

Kanban の browser client は happy-dom 上でも実行し、表示、検索、task 追加、button / drag 移動、競合時の再取得、board reload と mutation が重なった場合の fresh reload を回帰テストします。happy-dom は test 時だけ使う dev dependency で、pulse ui の runtime dependency には含まれません。

Usage

local link 後は pulse ... で実行できます。

pulse --db /tmp/pulse.db init
pulse --db /tmp/pulse.db add "Implement SQLite schema" --goal "MVP" --repo pulse --branch main --importance high --remaining-effort small
pulse --db /tmp/pulse.db list
pulse --db /tmp/pulse.db status
pulse --db /tmp/pulse.db summary
pulse --db /tmp/pulse.db brief
pulse --db /tmp/pulse.db ui
pulse --db /tmp/pulse.db claim 1 --agent codex
pulse --db /tmp/pulse.db beat 1 --agent codex --note "schema is in place"
pulse --db /tmp/pulse.db memo add 1 --agent codex --note "API contractを確認済み"
pulse --db /tmp/pulse.db memo list 1
pulse --db /tmp/pulse.db block 1 --reason "waiting for product decision"
pulse --db /tmp/pulse.db review 1 --note "ready for human review"
pulse --db /tmp/pulse.db release 1
pulse --db /tmp/pulse.db done 1 --note "merged"
pulse --db /tmp/pulse.db export

link せずに build artifact を直接実行する場合は以下でも動きます。

npm run build
./build/src/bin.js --db /tmp/pulse.db list

Local Kanban UI

既存の SQLite database をブラウザで確認・操作する場合は pulse ui を起動します。

pulse ui

既定では http://127.0.0.1:3210 に、次の順で Kanban 列を表示します。

未着手 → 作業中 → ブロック → レビュー → 完了

別の port を使う場合:

pulse ui --port 4321

local link を作らず source から試す場合:

npm run dev -- --db /tmp/pulse.db ui --port 4321

UI では以下を行えます。

• title / goal / context / repo / URL を横断した検索と agent 絞り込み
• 完了列は通常時に更新日時が新しい 5 件を表示し、過去の完了 task は検索で表示
• task 詳細、状態メモ、追記メモに保存された http / https URL をリンクとして表示
• task の追加
• task 追加時の重要度と残工数の設定
• card title 横での重要度と残工数の確認
• task 詳細からの重要度と残工数の更新
• task 詳細の確認
• task へのメモ追加と履歴確認
• drag & drop、または各 card の「移動」ボタンによる状態遷移
• claim 時の agent、block 時の reason、review / done 時の note の記録
• 10 秒ごとの自動更新と手動更新

状態遷移は既存 CLI と同じ storage operation を使うため、agent、note、timestamp、event も同じ規則で記録されます。done は終端で、UI から元の状態へは戻せません。別 tab や CLI で task が先に更新された場合は 409 Conflict として古い画面からの上書きを止め、最新状態を再取得します。

メモは状態遷移とは独立した追記専用の履歴です。完了済み task にも追加でき、GUI では新しいものから直近 100 件を表示します。全件を確認するときは pulse memo list TASK_ID を使います。メモ追加も task の更新時刻を進めるため、メモ保存前の古い画面から状態遷移を行うと 409 Conflict になり、最新の task を再取得します。

メモの agent は「誰が残したか」を表示する任意ラベルであり、認証済みの本人性を保証しません。

GitHub Pull Request がある作業を Pulse へ記録するときは、PR 番号だけでなく、確認済みの完全な PR URL も review / done note またはメモへ記載します。URL を確認できない場合は、repo 名から推測せず PR URL 未確認 と記録します。

server は 127.0.0.1 だけに bind し、LAN へ公開する --host option は提供しません。mutation は同一 Origin、起動ごとの CSRF token、JSON content type を要求し、全 response に CSP と no-store header を付けます。この token は browser からの cross-origin request を防ぐ境界であり、同じ OS user の local process に対する認証ではありません。

停止するときは、起動した terminal で Ctrl+C を押します。

Database Location

Pulse は database path を次の順で解決します。

1. --db /path/to/pulse.db
2. PULSE_DB=/path/to/pulse.db
3. ~/.pulse/pulse.db

default を repo 外に置くことで、複数 repo / worktree から同じ local state を共有しやすくしています。runtime database は Git 管理しません。

Commands

pulse init

SQLite database と schema を作成します。

pulse add

task を追加します。goal、context、agent、repo、worktree、branch、重要度、残工数を任意で記録できます。

pulse add "Fix failing tests" --goal "Release" --context "CI fails on sqlite migration" \
  --importance high --remaining-effort small

重要度は high / medium / low、残工数は small / medium / large です。二つは独立した判断材料として保存・表示し、自動的な総合score化や並び替えは行いません。

pulse priority

既存taskの重要度と残工数を更新します。省略した値は保持し、noneを指定した値は未設定へ戻します。

pulse priority 1 --importance high --remaining-effort small --agent codex
pulse priority 1 --remaining-effort medium
pulse priority 1 --importance none

重要度か残工数の少なくとも一方が必須です。CLIは現在値をtransaction内で読み直して更新するためDB破損は防ぎますが、expected revisionを要求しないlast-writer-winsです。UIはupdated_atをrevisionとして送信し、競合時は409 Conflictで古い画面からの上書きを防ぎます。

pulse list

task を一覧します。status / agent で絞り込めます。

pulse list --status blocked
pulse list --agent codex
pulse list --format json

pulse status

現在の状態を観測用に表示します。status count、attention 対象、active task、backlog、done を分けて表示します。

pulse status

pulse summary

現在の状態を短く共有するための要約を表示します。blocked / review の attention、active agent、次の todo を一目で確認できます。

pulse summary

pulse brief

AI が人に状況を返すときに、そのまま貼れる相談用 brief を表示します。全体判断、判断待ち、task ごとの goal / current / next action、risk、参照情報を固定順で出します。done task は件数だけにまとめます。pulse export は現在のsnapshotであり、状態変更eventの全履歴ではありません。

pulse brief

pulse ui

local browser 用の Kanban board を 127.0.0.1 で起動します。

pulse ui
pulse ui --port 4321

pulse claim / pulse release

task の担当 agent を設定、解除します。

pulse claim 1 --agent codex
pulse release 1

pulse block / pulse review / pulse done

task を blocked、review 待ち、done にします。

pulse block 1 --reason "needs API decision"
pulse review 1 --note "ready for human review"
pulse done 1 --note "tests passed"

pulse beat

task heartbeat を更新します。agent がまだ動いていることを人間が確認するための signal です。

pulse beat 1 --agent codex --note "working through review comments"

pulse memo

task に状態遷移とは独立したメモを追記し、履歴を表示します。メモは編集・削除せず、done の task にも追加できます。

pulse memo add 1 --agent codex --note "API contractを確認済み"
pulse memo list 1
pulse memo list 1 --format json

CLI の memo list は全履歴を表示します。agent は任意の表示ラベルで、認証情報ではありません。メモは task が存在する間は追記専用ですが、task 自体を pulse delete TASK_ID で削除すると関連メモも一緒に削除されます。恒久監査ログとしては扱わないでください。

pulse context

database全体で一つのcurrent chat title / goalを表示、更新、削除します。default databaseを共有するすべてのrepo/worktreeから同じ値が見えます。

pulse context show
pulse context set --chat-title "Pulse maintenance" --goal "Make Pulse maintainable"
pulse context clear

pulse delete

taskと関連event/memoを削除します。この操作は取り消せません。

pulse delete 1

pulse export

現在の状態を Markdown で出力します。

pulse export > pulse-state.md

Status Model

MVP の status は意図的に小さく保ちます。

• todo: まだ claim されていない
• claimed: agent が担当している
• blocked: 判断待ち、外部入力待ち
• review: 人間の review 待ち
• done: 完了

add、claim、release、block、review、done、beat、memo add、priorityはeventsにも行を追加します。deleteはeventを追加せず既存eventをcascade削除し、current contextのset/clearもeventを追加しません。public commandで表示できるevent履歴は現在memoだけです。pulse exportはtaskの現在snapshotであり、状態変更eventの全履歴は含みません。

MVP Scope

Pulse の MVP は、個人開発者が複数 AI agent の現在状態を手動で共有・観測できるところまでとします。

MVP に含めるもの:

• SQLite database の初期化
• task の追加
• agent claim / release
• todo / claimed / blocked / review / done の状態管理
• heartbeat 更新
• task ごとの追記専用メモ
• repo / worktree / branch / context の記録
• pulse list による機械可読 JSON と table 一覧
• pulse status による観測用の現在状態表示
• pulse summary による短い状況要約
• pulse brief による人間向け相談フォーマット
• pulse ui による local Kanban 表示、task 追加、メモ、状態遷移
• pulse export による Markdown 出力
• local command としての pulse ... 実行
• 100% coverage gate 付きの npm run verify

MVP に含めないもの:

• agent process の自動検出
• Git worktree / branch の自動 scan
• chat history の自動要約取り込み
• stale heartbeat の自動判定
• remote dashboard / multi-user authentication
• GitHub Issues / Pull Requests との同期
• 複雑な workflow engine