From dac1538d1fe54d2b402ec13755ab443354a293a6 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Sat, 31 Jan 2026 23:12:14 +0700
Subject: [PATCH] docs: add debugging guide and cli npm script

---
 CLAUDE.md    | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 package.json |  3 ++-
 2 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index a295d685b..42ce15017 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -39,6 +39,63 @@ PASEO_HOME=~/.paseo-blue PASEO_PORT=7777 npm run dev
 
 Both the server and Expo app are running in a Tmux session. See CLAUDE.local.md for system-specific session details.
 
+## Debugging
+
+### Daemon and CLI
+
+The Paseo daemon communicates via WebSocket. In the main checkout:
+- Daemon runs at `localhost:6767`
+- Expo app at `localhost:8081`
+- State lives in `~/.paseo`
+
+In worktrees or when running `npm run dev`, ports and home directories may differ. Never assume the defaults.
+
+Use `npm run cli` to run the local CLI (instead of the globally linked `paseo` which points to the main checkout). Always run `npm run cli -- --help` or load the `/paseo` skill before using it - do not guess commands.
+
+Use `--host <host:port>` to point the CLI at a different daemon (e.g., `--host localhost:7777`).
+
+### Quick reference CLI commands
+
+```bash
+npm run cli -- ls -a -g              # List all agents globally
+npm run cli -- ls -a -g --json       # Same, as JSON
+npm run cli -- inspect <id>          # Show detailed agent info
+npm run cli -- logs <id>             # View agent timeline
+npm run cli -- daemon status         # Check daemon status
+```
+
+### Agent state
+
+Agent data is stored at:
+```
+~/.paseo/agents/{cwd-with-dashes}/{agent-id}.json
+```
+
+To find an agent by ID:
+```bash
+find ~/.paseo/agents -name "{agent-id}.json"
+```
+
+To find an agent by title or other content:
+```bash
+rg -l "some title text" ~/.paseo/agents/
+rg -l "spiteful-toad" ~/.paseo/agents/
+```
+
+### Provider session files
+
+Get the session ID from the agent JSON file (`persistence.sessionId`), then:
+
+**Claude sessions:**
+```
+~/.claude/projects/{cwd-with-dashes}/{session-id}.jsonl
+```
+
+**Codex sessions:**
+```
+~/.codex/sessions/{YYYY}/{MM}/{DD}/rollout-{timestamp}-{session-id}.jsonl
+```
+
 ## Android
 
 Take screenshots like this: `adb exec-out screencap -p > screenshot.png`
diff --git a/package.json b/package.json
index b31dfad95..19dc4c33b 100644
--- a/package.json
+++ b/package.json
@@ -28,7 +28,8 @@
     "web": "npm run web --workspace=@paseo/app",
     "desktop": "npm run dev --workspace=@paseo/desktop",
     "desktop:build": "npm run build --workspace=@paseo/desktop",
-    "postinstall": "patch-package"
+    "postinstall": "patch-package",
+    "cli": "npx tsx packages/cli/src/index.js"
   },
   "devDependencies": {
     "concurrently": "^9.2.1",