blackroad/dotfiles/CLAUDE.md

CLAUDE.md

This is blackroad-scripts - the BlackRoad OS home directory (400+ shell scripts, CLI tools). See ~/.claude/CLAUDE.md for infrastructure context.

Development Commands

shellcheck ~/script-name.sh  # Lint bash scripts
bash -n ~/script-name.sh     # Syntax check only
bash -x ~/script-name.sh     # Debug mode (trace execution)
npm run dev                  # Wrangler dev server
npm run deploy              # Deploy to Cloudflare

Writing Scripts

Standard Header

#!/bin/bash
# Description of what this script does
# Usage: ./script-name.sh [args]

set -e  # Exit on error

Color Constants (BlackRoad Brand)

PINK='\033[38;5;205m'   # Hot pink (#FF1D6C)
AMBER='\033[38;5;214m'  # Amber (#F5A623)
BLUE='\033[38;5;69m'    # Electric blue (#2979FF)
VIOLET='\033[38;5;135m' # Violet (#9C27B0)
GREEN='\033[38;5;82m'   # Success
RESET='\033[0m'

Memory System

Every Claude session auto-loads the BlackRoad memory system via SessionStart hooks. You are expected to use it.

Scripts (all at ~/blackroad-operator/scripts/memory/)

Script	Purpose	Key commands
memory-system.sh	Core journal + chain	status, summary, log <action> <entity> "<details>"
memory-codex.sh	Solutions & patterns DB	search <query>, stats, add-solution, add-pattern
memory-infinite-todos.sh	Long-running projects	list, show <id>, add-todo <id> <text>, complete-todo <id> <todo-id>
memory-task-marketplace.sh	Claimable tasks (SQLite)	list, claim <id>, complete <id>, search <query>, stats
memory-til-broadcast.sh	Share learnings	broadcast <category> "<learning>", list, search <query>
memory-indexer.sh	FTS5 search + knowledge graph	search <query>, rebuild, patterns
memory-security.sh	Agent identity + audit	status, identity <name>, sign, audit
memory-collaboration.sh	Claude-to-Claude collab + Slack	register, announce, handoff, inbox, status, ask <agent>, group

Workflow for every session

1. Read the briefing — the SessionStart hooks show you active projects, codex stats, and available tasks
2. Check inbox — memory-collaboration.sh inbox shows pending handoffs from previous sessions
3. Search codex before solving — memory-codex.sh search "<problem>" — don't reinvent existing solutions
4. Pick up work — check memory-infinite-todos.sh list for projects with pending todos
5. Log your actions — memory-system.sh log <action> <entity> "<details>"
6. Broadcast learnings — memory-til-broadcast.sh broadcast <category> "<learning>"
7. Add solutions to codex — when you solve something new, add it so future sessions benefit
8. Mark todos complete — memory-infinite-todos.sh complete-todo <project-id> <todo-id>