📝 Add comprehensive CLAUDE.md for AI assistant guidance#2
📝 Add comprehensive CLAUDE.md for AI assistant guidance#2blackboxprogramming wants to merge 1 commit intomasterfrom
Conversation
Add documentation file explaining codebase structure, shell script conventions, color palette, development workflows, and key patterns for AI assistants working with the repository. https://claude.ai/code/session_01EDGpeDzs7fCPE16bapopVz
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
There was a problem hiding this comment.
Pull request overview
Adds a new CLAUDE.md “AI Assistant Guide” documenting the repository’s structure, Bash dashboard conventions (colors/UI patterns), and contributor workflows to help AI assistants work effectively in this codebase.
Changes:
- Introduces
CLAUDE.mdwith repo overview, key entrypoints, and dashboard category references - Documents shared Bash/ANSI color palette and common script patterns (headers,
--watch, controls) - Adds workflow guidance (commit format, PR process, CI/CD notes) and references to key files
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| **BlackRoad Dashboards** is a collection of 117 terminal-based dashboard scripts for monitoring BlackRoad OS infrastructure. All dashboards are written in pure Bash and display rich terminal UIs using ANSI escape codes with 24-bit RGB color support. | ||
|
|
There was a problem hiding this comment.
The doc states there are "117" dashboard scripts, but in-repo references disagree (e.g., br-dashboards.sh header says "all 28 terminal dashboards" and dashboard-launcher.sh says "92+ dashboards"). To avoid future drift, avoid hard-coding a specific count here (or compute it in scripts/docs generation).
| ## Environment Variables | ||
|
|
||
| | Variable | Description | | ||
| |----------|-------------| | ||
| | `CF_TOKEN` | Cloudflare API token for live stats | | ||
| | `GITHUB_TOKEN` | GitHub API access | | ||
| | `HOME/.blackroad-config` | Local configuration file | | ||
|
|
There was a problem hiding this comment.
This section is titled "Environment Variables", but HOME/.blackroad-config is a file path, not an environment variable. Either move it out of this table (e.g., into a "Configuration files" section) or rename the table/column to reflect that it includes file locations as well.
| 1. **Pure Bash:** All dashboards are pure bash scripts with no external dependencies beyond standard Unix tools | ||
| 2. **Truecolor Required:** Dashboards assume 24-bit color support | ||
| 3. **macOS Sound:** Sound effects use `afplay` (macOS only, silently fails elsewhere) | ||
| 4. **Network Checks:** Many dashboards ping real IP addresses - expect timeouts on offline networks | ||
| 5. **No Package Manager:** No npm, pip, or other package managers needed |
There was a problem hiding this comment.
The note "no external dependencies beyond standard Unix tools" is not accurate for macOS as written: many scripts use timeout (e.g., blackroad-live-dashboard.sh:25), which is not available on macOS by default. Suggest updating this guidance to list required commands (or note that macOS users may need coreutils/gtimeout or an alternative implementation).
| - Bitcoin: 0.1 BTC (Coinbase) | ||
| - Ethereum: 2.5 ETH (MetaMask) | ||
| - Solana: 100 SOL (Phantom) |
There was a problem hiding this comment.
Including specific portfolio holdings and wallet providers in-repo is sensitive (and quickly becomes stale). Recommend removing these amounts entirely or replacing with a redacted example (e.g., BTC_AMOUNT=<redacted>), and pointing to local env/config for real values if needed.
| - Bitcoin: 0.1 BTC (Coinbase) | |
| - Ethereum: 2.5 ETH (MetaMask) | |
| - Solana: 100 SOL (Phantom) | |
| - Example only (do not commit real holdings or wallet details). | |
| - Bitcoin: `BTC_AMOUNT=<redacted>` (wallet: `BTC_WALLET_PROVIDER=<redacted>`) | |
| - Ethereum: `ETH_AMOUNT=<redacted>` (wallet: `ETH_WALLET_PROVIDER=<redacted>`) | |
| - Solana: `SOL_AMOUNT=<redacted>` (wallet: `SOL_WALLET_PROVIDER=<redacted>`) |
| - Lucidia Prime: `192.168.4.38` | ||
| - BlackRoad Pi: `192.168.4.64` | ||
| - Lucidia Alt: `192.168.4.99` | ||
| - iPhone Koder: `192.168.4.68:8080` | ||
|
|
||
| ### Cloud Services | ||
| - **DigitalOcean:** Codex Infinity (`159.65.43.12`) | ||
| - **Cloudflare:** 16 zones, 8 Pages, 8 KV namespaces, 1 D1 database | ||
| - **GitHub:** 15 organizations, 66+ repositories | ||
| - **Railway:** 12+ active projects | ||
|
|
||
| ### Crypto Portfolio | ||
| - Bitcoin: 0.1 BTC (Coinbase) | ||
| - Ethereum: 2.5 ETH (MetaMask) | ||
| - Solana: 100 SOL (Phantom) | ||
|
|
There was a problem hiding this comment.
This documentation section exposes specific network IP addresses and detailed cryptocurrency holdings tied to concrete services and providers, which can be used by attackers for targeted network reconnaissance and social engineering (e.g., phishing for Coinbase, MetaMask, or Phantom access). If this repository is or becomes accessible outside a tightly controlled environment, consider removing or anonymizing real infrastructure addresses and asset amounts, replacing them with placeholders or high-level descriptions to avoid leaking sensitive operational and financial information.
| - Lucidia Prime: `192.168.4.38` | |
| - BlackRoad Pi: `192.168.4.64` | |
| - Lucidia Alt: `192.168.4.99` | |
| - iPhone Koder: `192.168.4.68:8080` | |
| ### Cloud Services | |
| - **DigitalOcean:** Codex Infinity (`159.65.43.12`) | |
| - **Cloudflare:** 16 zones, 8 Pages, 8 KV namespaces, 1 D1 database | |
| - **GitHub:** 15 organizations, 66+ repositories | |
| - **Railway:** 12+ active projects | |
| ### Crypto Portfolio | |
| - Bitcoin: 0.1 BTC (Coinbase) | |
| - Ethereum: 2.5 ETH (MetaMask) | |
| - Solana: 100 SOL (Phantom) | |
| - Lucidia Prime: `[internal IP redacted]` | |
| - BlackRoad Pi: `[internal IP redacted]` | |
| - Lucidia Alt: `[internal IP redacted]` | |
| - iPhone Koder: `[internal IP and port redacted]` | |
| ### Cloud Services | |
| - **DigitalOcean:** Codex Infinity (`[public IP redacted]`) | |
| - **Cloudflare:** 16 zones, 8 Pages, 8 KV namespaces, 1 D1 database | |
| - **GitHub:** 15 organizations, 66+ repositories | |
| - **Railway:** 12+ active projects | |
| ### Crypto Portfolio | |
| BlackRoad maintains diversified holdings across major chains (e.g., Bitcoin, Ethereum, Solana) using reputable exchanges and wallets. Specific balances and providers are intentionally omitted from this public documentation. |
Add documentation file explaining codebase structure, shell script
conventions, color palette, development workflows, and key patterns
for AI assistants working with the repository.
https://claude.ai/code/session_01EDGpeDzs7fCPE16bapopVz