Clawjournal setup

ClawJournal Setup

Interactive setup wizard. Walk the user through each step. Only pause when user input is required. Fix problems yourself when possible.

Principle: When something is broken or missing, fix it. Don't tell the user to go fix it themselves unless it genuinely requires their action. If a dependency is missing, install it. If a command fails, diagnose and repair.

0. Preflight

Check if clawjournal is already installed:

• command -v clawjournal && clawjournal status
• test -x ~/.clawjournal-venv/bin/clawjournal && ~/.clawjournal-venv/bin/clawjournal status

If found and the user is just resuming: skip to Step 2. If only ~/.clawjournal-venv/bin/clawjournal exists, use that full path for commands below. If found but the user wants the latest: re-run Step 1's installer (idempotent — it'll fast-forward the checkout and reinstall in place), then continue to Step 2. If not found: Continue to Step 1.

1. Install

Use the bundled installer scripts. They detect a Python 3.10+ interpreter, create an isolated venv at ~/.clawjournal-venv, and pip install -e the repo. Idempotent — safe to re-run.

First, ask: "Do you want the browser workbench? (Recommended — it's the primary review surface. Otherwise the CLI works alone.)" Use the answer to pick whether to pass the frontend flag below. If the user intends to share traces or enroll in OpenRefinery, also pass the sharing flag so the managed secret scanners are ready before packaging. Do not use Homebrew for those scanners.

macOS / Linux / WSL / Git Bash on Windows:

if [ -d ~/clawjournal/.git ]; then
  git -C ~/clawjournal pull --ff-only
else
  git clone https://github.com/rayward-external/clawjournal.git ~/clawjournal
fi

# Pick ONE based on the user's answer above:
~/clawjournal/scripts/install.sh                    # CLI only
~/clawjournal/scripts/install.sh --with-frontend    # also build the browser workbench (needs Node.js)
# Add --with-sharing to either command for sharing or OpenRefinery enrollment.

Native Windows PowerShell (no WSL / Git Bash):

if (Test-Path "$HOME\clawjournal\.git") {
  git -C "$HOME\clawjournal" pull --ff-only
} else {
  git clone https://github.com/rayward-external/clawjournal.git "$HOME\clawjournal"
}

# Pick ONE based on the user's answer above:
powershell -ExecutionPolicy Bypass -File "$HOME\clawjournal\scripts\install.ps1"                # CLI only
powershell -ExecutionPolicy Bypass -File "$HOME\clawjournal\scripts\install.ps1" -WithFrontend  # also build the browser workbench (needs Node.js)
# Add -WithSharing to either command for sharing or OpenRefinery enrollment.

The script's exit code and printed output tell you exactly what to do next. Common failure modes the script surfaces directly:

• Python 3.10+ not found — install via the platform hint the script prints, then re-run. macOS users may also need xcode-select --install to get a working python3.
• python3 -m venv fails on Debian/Ubuntu — run sudo apt install -y python3-venv python3-full, then re-run the script.
• node / npm missing when --with-frontend was requested — the script skips the frontend with a warning. Install Node.js (macOS: brew install node, Linux: sudo apt-get install -y nodejs npm, Windows: nodejs.org) and re-run with the flag.
• A managed secret scanner download fails when --with-sharing / -WithSharing was requested — check the printed network or checksum diagnostic and re-run the same installer. Do not bypass the sharing gate.

Verify (POSIX):

~/.clawjournal-venv/bin/clawjournal status

Verify (PowerShell):

& "$HOME\.clawjournal-venv\Scripts\clawjournal.exe" status

2. Scan Sessions

Discover all local coding agent sessions:

~/.clawjournal-venv/bin/clawjournal scan

This indexes sessions from Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Kimi CLI, and Cline — whatever is present on the machine.

Show the user a summary: "Found N sessions across M sources."

If zero sessions found:

• Check if the user has any supported coding agents installed
• Common issue: sessions live in non-default paths — ask the user

3. Score & Auto-Triage (optional but recommended)

Ask: "Would you like me to auto-score your sessions? Each session gets two AI ratings: a failure-value score (1-5, the primary signal for finding teachable agent failures on real work) and a productivity score (1-5, legacy compatibility)."

If yes:

~/.clawjournal-venv/bin/clawjournal score --batch --source failure-corpus --auto-triage

--source failure-corpus scopes to the supported sources (claude, codex, opencode, openclaw); auto-triage archives productivity-1 sessions only when failure value is 1-2.

Show summary: "N sessions scored. Failure-value distribution: ... M productivity-1 low-failure-value sessions auto-archived as noise."

If no: skip to Step 4.

4. Launch Workbench

Ask: "How would you like to review your traces?"

Option A — Browser UI (recommended for local machines):

Check whether the frontend is already built:

test -f ~/clawjournal/clawjournal/web/frontend/dist/index.html && echo built || echo missing

If missing, re-run the installer with the frontend flag (POSIX):

~/clawjournal/scripts/install.sh --with-frontend

PowerShell equivalent:

powershell -ExecutionPolicy Bypass -File "$HOME\clawjournal\scripts\install.ps1" -WithFrontend

Then start the workbench:

~/.clawjournal-venv/bin/clawjournal open

This starts or reuses the local daemon, waits a bounded time for readiness, opens the browser, and then returns. Do not wait for a foreground daemon to exit.

Tell the user: "Your workbench is open at localhost:8384. Everything is 100% local. Use the Inbox to triage traces, Search to find sessions, and Bundles to assemble exports."

Option B — Terminal review (for remote VMs or headless environments):

~/.clawjournal-venv/bin/clawjournal inbox --json --limit 15

Parse the JSON and present traces as a numbered list. Then guide triage interactively.

For remote VMs: use clawjournal serve --remote in a dedicated terminal or background process and follow the SSH tunnel command it prints. serve is a foreground, long-running daemon command; do not wait for it to exit before continuing the setup conversation.

5. Done

Show summary:

• ClawJournal version installed
• Number of sessions indexed
• Number scored/triaged (if applicable)
• How to access the workbench

Tell the user:

• "You can review and share traces anytime with /clawjournal"
• "Score sessions with /clawjournal-score"
• "Everything stays 100% local until you explicitly choose to share"

Before sharing: source scope + project confirmation

Sharing/exporting is gated until two one-time confirmations are set — this prevents accidentally contributing traces from a source or project the user didn't intend. Local review and scoring do not need these; only the first share does. The workbench Share flow and clawjournal export both block until both are in place:

• Source scope — explicitly choose which agents' traces are in scope:

  ~/.clawjournal-venv/bin/clawjournal config --source <claude|codex|gemini|all>
  

• Project confirmation — confirm the projects whose traces may be shared:

  ~/.clawjournal-venv/bin/clawjournal config --confirm-projects
  

It's fine to defer this until the user is ready to contribute — if they try to share first, ClawJournal prints the exact command to run.

Troubleshooting

clawjournal command not found after install: Use ~/.clawjournal-venv/bin/clawjournal directly, or add the venv bin directory to your shell PATH.

No sessions found: Make sure you've used a supported coding agent (Claude Code, Codex, Gemini CLI, etc.) on this machine. Sessions are stored in agent-specific directories under your home folder.

Permission errors on scan: ClawJournal reads session files from ~/.claude/, ~/.codex/, etc. Ensure these directories are readable.

Browser UI shows a placeholder page: The frontend has not been built yet. Re-run the installer with the frontend flag: ~/clawjournal/scripts/install.sh --with-frontend (or .\scripts\install.ps1 -WithFrontend on PowerShell). Requires Node.js.

venv issues on Linux: If you see externally-managed-environment, make sure you're installing into the venv: python3 -m venv ~/.clawjournal-venv && ~/.clawjournal-venv/bin/python -m pip install -e ~/clawjournal.