From 33d6128e52d7f1329fea7ac483de948cefea060c Mon Sep 17 00:00:00 2001
From: Lukas Kosina <lukas.kosina@wflow.com>
Date: Fri, 6 Mar 2026 18:13:20 +0100
Subject: [PATCH] Update README to reflect current application state

- Add missing CLI commands (stop, restart) and --no-open flag
- Document browser notifications and event logging features
- Expand session states table with PermissionRequest, PreToolUse, PostToolUse events
- Document install mode extras (shortcuts, protocol handler, auto-launch)
- Add dashboard features section (notifications, logging, server controls, idle cleanup)
- Add lint commands to development section

Fixes #54
---
 README.md | 47 +++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 39 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index d66e1c0..72499c7 100644
--- a/README.md
+++ b/README.md
@@ -38,7 +38,11 @@ npx @kosinal/claude-code-dashboard install              # persistent install
 npx @kosinal/claude-code-dashboard install --port 9000  # custom port
 ```
 
-Copies the server to `~/.claude/dashboard/` and installs persistent hooks. The dashboard auto-launches in the background when any Claude Code session starts.
+Copies the server to `~/.claude/dashboard/` and installs persistent hooks. When any Claude Code session starts, the dashboard auto-launches in the background and opens in your browser.
+
+Install mode also creates:
+- A desktop/Start Menu shortcut to open the dashboard
+- A `claude-dashboard://` protocol handler for quick access
 
 ### Uninstall
 
@@ -46,7 +50,14 @@ Copies the server to `~/.claude/dashboard/` and installs persistent hooks. The d
 npx @kosinal/claude-code-dashboard uninstall
 ```
 
-Removes hooks from `settings.json` and deletes `~/.claude/dashboard/`.
+Removes hooks from `settings.json`, deletes `~/.claude/dashboard/`, and cleans up shortcuts and protocol handlers.
+
+### Stop & restart
+
+```bash
+npx @kosinal/claude-code-dashboard stop      # gracefully stop a running server
+npx @kosinal/claude-code-dashboard restart   # restart, or start fresh if not running
+```
 
 ### Options
 
@@ -54,16 +65,34 @@ Removes hooks from `settings.json` and deletes `~/.claude/dashboard/`.
 |---|---|
 | `--port <number>` | Port to listen on (default: `8377`) |
 | `--no-hooks` | Start the server without installing hooks |
+| `--no-open` | Don't auto-open browser on start |
 | `-h`, `--help` | Show help message |
 
+## Dashboard features
+
+- **Real-time session cards** — each Claude Code session appears as a card with status, project folder, working directory, last event, and time-ago timestamp
+- **Status indicators** — animated dots show running (yellow, pulsing), waiting for input (blue, breathing), or done (green, static)
+- **Browser notifications** — opt-in desktop notifications when a session transitions to "waiting for input" (toggle in the header)
+- **Event logging** — toggle detailed event logging to `~/.claude-code-dashboard/logs/` from the dashboard footer
+- **Server controls** — restart or stop the server directly from the dashboard UI
+- **Connection indicator** — visual feedback showing whether the browser is connected to the server
+- **Idle cleanup** — sessions are automatically removed after 5 minutes of inactivity
+
 ## Session states
 
-| Hook event | Dashboard status |
-|---|---|
-| `SessionStart` | Waiting for input |
-| `UserPromptSubmit` | Running |
-| `Stop` | Waiting for input |
-| `SessionEnd` | Done |
+The dashboard tracks session status based on multiple hook events:
+
+| Hook event | Dashboard status | Description |
+|---|---|---|
+| `SessionStart` | Done | New session, no prompt yet |
+| `UserPromptSubmit` | Running | User submitted a prompt |
+| `PreToolUse` | Waiting / Running | Waiting if tool needs approval; running if auto-approved |
+| `PermissionRequest` | Waiting | Tool requires explicit user permission |
+| `PostToolUse` | Running | Tool finished, Claude is working |
+| `Stop` | Done | Session stopped |
+| `SessionEnd` | *(removed)* | Session removed from dashboard |
+
+The `PreToolUse` logic is context-aware: interactive tools (Write, Edit, NotebookEdit, ExitPlanMode, AskUserQuestion) set status to "waiting", unless the session is in `acceptEdits` mode where edit tools are auto-approved.
 
 Sessions are sorted by status (running first, then waiting, then done) and by last update time within each group.
 
@@ -82,6 +111,8 @@ Sessions are sorted by status (running first, then waiting, then done) and by la
 npm install          # install dev dependencies
 npm run build        # bundle with tsup (ESM, node18 target)
 npm test             # run tests (node:test with --experimental-strip-types)
+npm run lint         # check for lint issues
+npm run lint:fix     # auto-fix lint issues
 ```
 
 ## License