# Larry-Anywhere — Manual Tool Cheat Sheet (no-Larry / offline mode) Every Larry-Anywhere capability is also a standalone bash script under `lib/`. When the internet is down, you're on a plane, or the Anthropic API is unreachable, you can drive these tools directly from the shell. **Larry just sequences them — the tools work without Larry.** This page documents every command with copy-paste examples. Print it. --- ## The front door: `larry tools` (v0.8.14) You don't have to memorize the `lib/` paths. The `larry` command itself is the discoverable entry point for manual-tools mode — it works with **no REPL, no API, no LLM**, so it's the lifeline on a locked-down box where the model API is blocked: ```bash larry tools list # every tool + a one-line description, grouped larry tools [args] # run a tool by hand (no args → its --help) larry tools --help # usage, flags, expected input/output + example larry tools help # what manual-tools mode is # Examples — the name is the script minus ".sh": larry tools nc-parse list-protocols "$HCISITEDIR/NetConfig" larry tools hl7-field PID.3 /tmp/sample.hl7 larry tools nc-status sites ``` `larry tools …` runs **before** any self-update or network call, so a fresh install with the API blocked still gives you the full toolkit. Equivalent to calling `lib/.sh …` directly (documented below) — use whichever you prefer. ### When the API is blocked If you launch the interactive REPL on a box where corporate security blocks `api.anthropic.com` (e.g. Cisco Umbrella returns a 403, TLS inspection trips `unable to get local issuer certificate`, or egress is refused), Larry **detects the block and guides you into manual-tools mode** instead of dumping a raw curl error: ``` Can't reach the model API — looks like a corporate network block. What happened: TLS interception (an untrusted/MITM certificate ...). The Cloverleaf tools still work — run them by hand (no API/LLM needed): larry tools list To use the AI brain: ask IT to allowlist api.anthropic.com, or run from a network that permits it. ``` This is graceful degradation and honest guidance only. Larry will **not** try to bypass, mask, proxy around, or otherwise circumvent a corporate security control on a PHI box — that is off the table by design. The fix is to get the endpoint allowlisted by IT, or run from a permitted network. --- ## Conventions - `$LARRY_HOME` defaults to `~/.larry/`. Lib scripts live at `$LARRY_HOME/lib/`. - For brevity, examples below use `lib/.sh`. From `$LARRY_HOME/`, that's `./lib/.sh`. Or add `$LARRY_HOME/lib` to your PATH. - `$HCIROOT` = Cloverleaf install root (e.g. `/opt/cloverleaf/cis2025/integrator`). - `$HCISITE` = current site name (e.g. `adt`). - `$HCISITEDIR` = `$HCIROOT/$HCISITE`. Set these before running anything site-specific: ```bash export HCIROOT=/opt/cloverleaf/cis2025/integrator export HCISITE=adt export HCISITEDIR="$HCIROOT/$HCISITE" ``` --- ## Auto-update & origin `larry.sh` (and `install-larry.sh`) fetch updates from a single Gitea origin: `$LARRY_BASE_URL` (default `https://git.bjnoela.com/bryan/cloverleaf-larry/raw/branch/main`). Env vars that control fetching: - `LARRY_BASE_URL` — override the origin (fork/mirror). No trailing slash. - `LARRY_NO_UPDATE=1` (or `--no-update`) — skip the self-update entirely. - `LARRY_GITEA_TOKEN` (alias `GITEA_TOKEN`) — a Gitea **personal access token** (read scope) for **authenticated fetch against a PRIVATE repo**. When set, every update/install fetch adds `Authorization: token `. The token value is never logged. Use this when the Gitea repo is private or the instance has `REQUIRE_SIGNIN_VIEW=true`, so you don't have to flip the repo public. ```bash LARRY_GITEA_TOKEN= larry # authenticated auto-update LARRY_GITEA_TOKEN= bash install-larry.sh # authenticated install ``` **Hardening (v0.8.4):** every remote fetch is content-validated before the bytes are trusted. If the origin returns the Gitea HTML *Sign-In* page (which Gitea serves at HTTP 200 for an unauthenticated read of a private repo), the installer/updater **fails loud** with an actionable error and does **not** overwrite any real file — instead of silently parsing the HTML as VERSION/MANIFEST/script content (the bug that stranded a client at v0.7.3). The remedy is exactly what the error states: make the repo public + `REQUIRE_SIGNIN_VIEW=false`, **or** set `LARRY_GITEA_TOKEN`. --- ## Authentication (`larry-auth.sh`, `lib/oauth.sh`) Only needed if you're running the Larry REPL (`larry.sh`). The lib/ tools themselves never call Anthropic — they're pure local bash. ```bash larry-auth.sh login # OAuth via Claude.ai subscription larry-auth.sh status # show current auth state + expiry larry-auth.sh refresh # force-refresh the access token larry-auth.sh logout # delete tokens (revert to API key) ``` Falling back to API key: edit `$LARRY_HOME/.env` with `ANTHROPIC_API_KEY=sk-ant-...`, chmod 600. Larry uses API key whenever `$LARRY_HOME/.oauth.json` is absent. --- ## NetConfig parsing — read (`lib/nc-parse.sh`) The foundational reader. Every other NetConfig tool calls this. ```bash # List every protocol (thread) in a NetConfig file lib/nc-parse.sh list-protocols "$HCISITEDIR/NetConfig" # List every process lib/nc-parse.sh list-processes "$HCISITEDIR/NetConfig" # Find the line where a thread is declared lib/nc-parse.sh protocol-line "$HCISITEDIR/NetConfig" ADTto_3m # → 488 # Get the FULL TCL block for one protocol lib/nc-parse.sh protocol-block "$HCISITEDIR/NetConfig" IB_ADT_muxS # Extract a top-level field value lib/nc-parse.sh protocol-field "$HCISITEDIR/NetConfig" IB_ADT_muxS PROCESSNAME # → ADT lib/nc-parse.sh protocol-field "$HCISITEDIR/NetConfig" IB_ADT_muxS OBWORKASIB # → 1 # Drill into nested blocks via dotted path — HOST/PORT/TYPE/ISSERVER live inside PROTOCOL{} lib/nc-parse.sh protocol-nested "$HCISITEDIR/NetConfig" ADTto_3m PROTOCOL.PORT # → 51006 lib/nc-parse.sh protocol-nested "$HCISITEDIR/NetConfig" ADTto_3m PROTOCOL.HOST # → SHD360ENCINT02T lib/nc-parse.sh protocol-nested "$HCISITEDIR/NetConfig" ORU_fr_OPACS PROTOCOL.ISSERVER # → 1 (it's a TCP listener) # TSV summary of every protocol — direction, port, host, type at a glance lib/nc-parse.sh protocol-summary "$HCISITEDIR/NetConfig" lib/nc-parse.sh protocol-summary "$HCISITEDIR/NetConfig" --filter adt # only ADT-ish names # Routing destinations (what does X route to?) lib/nc-parse.sh destinations "$HCISITEDIR/NetConfig" IB_ADT_muxS # Routing sources (what routes INTO X?) — inverse lib/nc-parse.sh sources "$HCISITEDIR/NetConfig" ADTto_CodaMetrix # Xlate files referenced (one protocol, or all) lib/nc-parse.sh xlate-refs "$HCISITEDIR/NetConfig" IB_ADT_muxS lib/nc-parse.sh xlate-refs "$HCISITEDIR/NetConfig" # all in file # TCL procs referenced lib/nc-parse.sh tclproc-refs "$HCISITEDIR/NetConfig" IB_ADT_muxS # Get just the DATAXLATE routing block (the heart of routing config) lib/nc-parse.sh route-block "$HCISITEDIR/NetConfig" IB_ADT_muxS ``` > `destinations` / `sources` are ONE HOP. To trace a full multi-hop chain, use > the route-chain tracer below (`nc-paths.sh`) — do not loop these by hand. --- ## Route-chain path tracer (`lib/nc-paths.sh`) — the single walker Enumerates the full root-to-leaf message path(s). **Within a site** the next hop follows the DATAXLATE `{ DEST }` routing graph (never an `ICLSERVERPORT` walk — so it cannot recur the old `paths.tcl` crash). Output columns **SITE THREAD HOPS PATH** — HOPS is the thread count in the chain, PATH is the chain joined by ` -> ` (one row per enumerated path; a branch yields multiple rows). THREAD is the ROOT (first node) of the chain. > **Upstream note (Vera m2):** for `--up` chains the THREAD column shows the feeder > ROOT (the most-upstream source) and the queried thread is the chain TERMINUS — > PATH reads `source -> ... -> queried_thread`. **Cross-site by `destination` block (v0.8.20)** — Cloverleaf links sites through named `destination` blocks (the inter-cloverleaf / ICL routing table), not by thread name and not by blindly matching ports. A top-level `destination { ... }` declares `{ SITE } { THREAD } { PORT }` — the remote inbound it connects to and the link port. A thread's DATAXLATE `DEST` may name either a LOCAL protocol (intra-site hop) or a `destination` block; a `DEST` naming a destination block is the cross-site hop, resolved by name to the exact remote `(site, thread)`. The `PORT` equals the remote thread's listen/ICL port (corroboration); `ICLSERVERPORT` is still read GUARDED (absent / `{}` → skipped, never the un-guarded `keylget` that crashed `paths.tcl`). Upstream cross-site feeders of an inbound = every destination block (any site) resolving to it plus the threads that `DEST` to those blocks. The whole route graph is parsed ONCE per run (`nc-parse.sh index`) into memory and walked with O(1) lookups — no subprocess / re-parse per hop. `--site-only` scopes to one site. Cycle-safe; always terminates. ```bash # One thread — every full path containing it (default), table output. # Either pass , or let it auto-locate under $HCIROOT. lib/nc-paths.sh pharm_adt_in pharmacy lib/nc-paths.sh IB_ADT_muxS anc # cross-site chain followed # Only downstream chains from a thread / only upstream feeders lib/nc-paths.sh IB_ADT_muxS anc --downstream # --up: THREAD column = the feeder ROOT; the queried thread (ADTto_CodaMetrix) # is the chain TERMINUS, i.e. PATH = feeder_root -> ... -> ADTto_CodaMetrix. lib/nc-paths.sh ADTto_CodaMetrix codametrix --upstream # Stop at the site boundary (no cross-site join) lib/nc-paths.sh IB_ADT_muxS anc --site-only # Whole-site / whole-environment chain inventory (every entry-point chain) lib/nc-paths.sh --all # every site under $HCIROOT lib/nc-paths.sh --all --site anc # scope to one site # Formats + HCIROOT override lib/nc-paths.sh pharm_adt_in pharmacy --format jsonl lib/nc-paths.sh --all --hciroot /other/install/integrator --format tsv ``` In the REPL this is the `/paths` slash command (the `site` defaults to the current `$HCISITE` if omitted), and the LLM reaches it via the `nc_paths` tool for any "show me the path / what feeds X / full route" question: ```text /paths pharm_adt_in pharmacy /paths IB_ADT_muxS anc --site-only /paths --all ``` --- ## Inbound thread classifier (`lib/nc-inbound.sh`) Identifies inbound threads — TCP listeners directly fed by upstream clients (Epic etc.), or ICL/file inbounds fed via Cloverleaf's internal link. ```bash # Every inbound thread (both classes), table format lib/nc-inbound.sh "$HCISITEDIR/NetConfig" --format table # Just real TCP listeners (the "directly fed by upstream" subset) lib/nc-inbound.sh "$HCISITEDIR/NetConfig" --mode tcp-listen --format table # Just ICL/file inbounds lib/nc-inbound.sh "$HCISITEDIR/NetConfig" --mode icl-or-file --format table # JSONL for piping into other tools lib/nc-inbound.sh "$HCISITEDIR/NetConfig" --mode tcp-listen --format jsonl ``` --- ## Cross-site finder (`lib/nc-find.sh`) — the v1 tbn/tbp/tbh/tbpr/where replacements Walks every NetConfig under `$HCIROOT` (or a passed list) and returns matches. ```bash # tbn equivalent: partial name match lib/nc-find.sh --name adt --format table # tbp equivalent: exact port lib/nc-find.sh --port 51204 --format table # tbh equivalent: substring on host lib/nc-find.sh --host SHD360 --format table # tbpr equivalent: substring on PROCESSNAME lib/nc-find.sh --process codametrix --format table # v1 ` where` — locate a thread across all sites lib/nc-find.sh --where IB_ADT_muxS --format table # Threads referencing a specific xlate file lib/nc-find.sh --xlate Epic_ADT_CodaMetrix --format table # Threads referencing a specific TCL proc lib/nc-find.sh --tclproc trxId_IB_ADT_muxS --format table # Override HCIROOT or pass explicit netconfigs lib/nc-find.sh --name adt --hciroot /other/install/integrator --format table lib/nc-find.sh --name adt --netconfigs "/a/NetConfig:/b/NetConfig" --format jsonl ``` --- ## Message search — smat queries (`lib/nc-msgs.sh`) Smat databases are **SQLite 3**. Reads via native `sqlite3 -ascii` — no Cloverleaf binary involved. ```bash # Count messages in a thread's smat lib/nc-msgs.sh ADTto_3m --format count # Recent 5 messages (text format = segments per line, with metadata header) lib/nc-msgs.sh ADTto_3m --limit 5 --format text # OUTPUT FORMATS: # text (default) segments per line + metadata header per message # oneline one message per line; segments separated by ⏎ marker # fields each non-empty field on its own line: "SEG.N: value" # mp alias for fields (v1 `mp`-style) # labeled fields with alias names where known: "MSH.9 (msg_type): ADT^A08" # raw raw bytes; messages separated by 0x1c (FS) — for piping # json structured JSON # count just the count lib/nc-msgs.sh ADTto_3m --limit 3 --format oneline lib/nc-msgs.sh ADTto_3m --limit 1 --format fields lib/nc-msgs.sh ADTto_3m --limit 1 --format labeled # adds friendly aliases # Time range — supports human expressions lib/nc-msgs.sh ADTto_3m --after "3 days ago" --format count lib/nc-msgs.sh ADTto_3m --after "2026-05-20" --before "2026-05-26 12:00:00" # Filter operators (paths accept either . or - separators; same field name aliases everywhere): # PATH=VALUE exact equality (any repetition) # PATH!=VALUE not equal (no repetition matches) # PATH~VALUE contains, case-insensitive # PATH!~VALUE does not contain, case-insensitive # PATH=NULL empty / absent / "" — any of those # PATH= same as =NULL # PATH=* wildcard — any non-empty value # PATH!=NULL present (any non-empty repetition) # Multiple --field flags AND together. For OR, run two queries. # Examples using field-name ALIASES (case-insensitive; auto-translates to SEG.N) lib/nc-msgs.sh ADTto_3m --field 'mrn=5720501458' --format count lib/nc-msgs.sh ADTto_3m --field 'account_number=623000286' --format text lib/nc-msgs.sh ADTto_3m --field 'event=A08' --format count lib/nc-msgs.sh ADTto_3m --field 'visit=*' --format count # any non-empty lib/nc-msgs.sh ADTto_3m --field 'ssn=NULL' --format count # missing SSN lib/nc-msgs.sh ADTto_3m --field 'name~smith' --format text # contains lib/nc-msgs.sh ADTto_3m --field 'name!~test' --format count # production-looking lib/nc-msgs.sh ADTto_3m --field 'event=A08' --field 'visit=*' # AND of both # Component access: name.2 (PID.5 component 2 = given name) lib/nc-msgs.sh ADTto_3m --field 'name.2=SALLY' --format count # Dash syntax (cheat-sheet style): lib/nc-msgs.sh ADTto_3m --field 'PV1-3.4=100200' --format count # JSON output for piping lib/nc-msgs.sh ADTto_3m --field PID.3=5720501458 --format json | jq # Explicit smatdb path (skip auto-locate) lib/nc-msgs.sh ADTto_3m --db "$HCISITEDIR/exec/processes/3M/ADTto_3m.smatdb" --format count # Raw format (for piping into route-test inputs) — messages separated by 0x1c lib/nc-msgs.sh ADTto_3m --limit 10 --format raw > inputs.msgs ``` --- ## HL7 field extraction (`lib/hl7-field.sh`) Extract specific fields from a single HL7 message. ```bash # Read message from file, extract MRN lib/hl7-field.sh PID.3 /path/to/message.hl7 # → 5720501458 # From stdin cat msg.hl7 | lib/hl7-field.sh MSH.10 # → 27175 (message control ID) # Component extraction lib/hl7-field.sh MSH.9 msg.hl7 # → ADT^A08 lib/hl7-field.sh MSH.9.1 msg.hl7 # → ADT lib/hl7-field.sh MSH.9.2 msg.hl7 # → A08 # Patient name (whole field + components) lib/hl7-field.sh PID.5 msg.hl7 # → MORRIS^SALLY^^^^^^LHS^^^^^LEH^M lib/hl7-field.sh PID.5.1 msg.hl7 # → MORRIS (family name) lib/hl7-field.sh PID.5.2 msg.hl7 # → SALLY (given name) # Pipe smat dump → extract → sort | uniq lib/nc-msgs.sh ADTto_3m --limit 100 --format raw \ | awk -v RS=$'\x1c' '{print $0 > "/tmp/m"NR; system("lib/hl7-field.sh PID.3 /tmp/m"NR)}' ``` --- ## HL7-aware diff (`lib/hl7-diff.sh`) Compare two HL7 files (or multi-message dumps) with field-level normalization. ```bash # Default — ignores MSH.7 (timestamp); shows everything else lib/hl7-diff.sh left.hl7 right.hl7 # Add more fields to ignore lib/hl7-diff.sh --ignore "MSH.7,MSH.10,EVN.6" left.hl7 right.hl7 # Inverse: ONLY compare specific fields lib/hl7-diff.sh --include-fields "PID.3,PID.18,MSH.9" left.hl7 right.hl7 # Just count the differences lib/hl7-diff.sh --format count left.hl7 right.hl7 # → 5 # TSV output for parsing lib/hl7-diff.sh --format tsv left.hl7 right.hl7 # columns: msg_idx \t field_path \t left_value \t right_value ``` --- ## Jump thread generation (`lib/nc-make-jump.sh`) Generates the 3-thread cross-environment data-replay pattern: `linux__out` on OLD, `windows__in` + `windows__out` in NEW's `server_jump` site. Output is plain TCL text — no file writes. ```bash # Generate for one inbound, target new linux host:port, output to stdout lib/nc-make-jump.sh "$HCISITEDIR/NetConfig" \ --inbound ORU_fr_OPACS \ --new-host newlinux01.test \ --jump-port 61204 # Write each artifact to separate files lib/nc-make-jump.sh "$HCISITEDIR/NetConfig" \ --inbound ORU_fr_OPACS \ --new-host newlinux01.test \ --jump-port 61204 \ --out-prefix /tmp/oru_jump # Produces: # /tmp/oru_jump.old_out.tcl — paste into OLD env NetConfig # /tmp/oru_jump.new_in.tcl — paste into NEW server_jump NetConfig # /tmp/oru_jump.new_out.tcl — paste into NEW server_jump NetConfig # /tmp/oru_jump.route_add.tcl — splice into OLD inbound's DATAXLATE # Override defaults lib/nc-make-jump.sh "$HCISITEDIR/NetConfig" \ --inbound ORU_fr_OPACS --new-host newlinux01 --jump-port 61204 \ --inbound-host 10.0.0.5 # NEW-side outbound dials this instead of 127.0.0.1 --process-jump migration_jump # different process on NEW than default "server_jump" --encoding UTF8 # override if not ASCII ``` --- ## NetConfig modification — journaled writes (`lib/nc-insert-protocol.sh`) Inserts new protocol blocks and splices route entries. **Every write is journaled** — backup, diff, atomic replace. ```bash # Insert a new protocol at end of file lib/nc-insert-protocol.sh insert "$HCISITEDIR/NetConfig" /tmp/oru_jump.old_out.tcl # → journal entry: 2026-05-26-09xxxx/001_NetConfig # rollback: larry-rollback.sh --entry 2026-05-26-09xxxx/001_NetConfig # Insert before/after a named anchor protocol lib/nc-insert-protocol.sh insert "$HCISITEDIR/NetConfig" /tmp/new_block.tcl --mode after --anchor IB_ADT_muxS lib/nc-insert-protocol.sh insert "$HCISITEDIR/NetConfig" /tmp/new_block.tcl --mode before --anchor ADTto_3m # Splice a route entry into an existing protocol's DATAXLATE block lib/nc-insert-protocol.sh add-route "$HCISITEDIR/NetConfig" ORU_fr_OPACS /tmp/oru_jump.route_add.tcl ``` After any write, see what changed: ```bash larry-rollback.sh --list # all journal entries larry-rollback.sh --list --session # one session cat "$LARRY_HOME/journal//manifest.md" # human-readable summary cat "$LARRY_HOME/journal//files/NNN_*.diff" # the unified diff ``` Roll back: ```bash larry-rollback.sh --target "$HCISITEDIR/NetConfig" # all changes to this file, newest first larry-rollback.sh --session 2026-05-26-09xxxx --yes # whole session, no prompt larry-rollback.sh --last 1 # just the most recent write larry-rollback.sh --entry 2026-05-26-09xxxx/001_NetConfig # one specific entry larry-rollback.sh --dry-run --session ... # preview without changing anything ``` Pre-rollback copies land at `.larry-prerollback.` so you can redo. --- ## System documentation (`lib/nc-document.sh`) Walks every NetConfig under `$HCIROOT`, finds threads matching a pattern, composes a markdown knowledge entry. ```bash # Auto-derived doc to stdout lib/nc-document.sh --name codametrix # Write to a file with context fields lib/nc-document.sh --name codametrix \ --out "$LARRY_HOME/knowledge/codametrix.md" \ --title "CodaMetrix Coding System" \ --status "production" \ --poc-vendor "John Doe at CodaMetrix, jdoe@codametrix.com" \ --poc-internal "Sarah Smith, Integration Team" \ --escalation "Page #integration-oncall in Slack" \ --open-items "- Renewal Q3 2026" \ --notes "Lives in epic site mostly; 1 thread in ancout" # Different scope sources lib/nc-document.sh --name "3M" --hciroot /other/integrator --out /tmp/3m.md lib/nc-document.sh --name epic_adt --netconfigs "$HCIROOT/epic/NetConfig:$HCIROOT/ancout/NetConfig" ``` Output: a complete markdown doc with cluster threads, sources, destinations, xlates, tclprocs, plus the placeholder context sections for the team. --- ## Interface diff (`lib/nc-diff-interface.sh`) Compares one interface (and connected threads) between two NetConfigs. ```bash # Diff ADTto_3m + 1 hop of connected threads between test and prod lib/nc-diff-interface.sh \ --interface ADTto_3m \ --left /test/integrator/ancout/NetConfig \ --right /prod/integrator/ancout/NetConfig \ --left-label TEST --right-label PROD \ --depth 1 \ --out /tmp/adt_diff.md # Walk further out lib/nc-diff-interface.sh --interface ADTto_3m \ --left /test/integrator/ancout/NetConfig \ --right /prod/integrator/ancout/NetConfig \ --depth 3 \ --out /tmp/adt_chain_diff.md # Include table file diffs too (.tbl referenced by xlates/tclprocs) lib/nc-diff-interface.sh --interface ADTto_3m ... --include-tables ``` Output: markdown report with cluster overview, per-thread protocol-block diff, per-xlate file diff, per-tclproc file diff. --- ## Cross-environment Larry — how the boxes communicate **They don't, directly.** Each Larry on each box is independent. For regression testing across two firewalled environments, the workflow is: ``` env-A (Windows) env-B (Linux) nc-regression --phase env-a → nc-regression --phase env-b --bundle-out /tmp/reg.tar.gz --bundle-in /tmp/reg.tar.gz │ │ └────── you move the bundle ────────┘ (scp, gh release, USB, shared mount, etc.) ``` The `--bundle-out` flag (after env-A phases 1-3) produces a tarball with: - `inputs/*.msgs` — sampled messages from env-A smatdbs - `outputs/env-a/*/*.out` — env-A route_test outputs - `manifest.json` — env-A metadata + hints - `inbounds.txt` — the threads tested - `README.md` — instructions for the env-B side Move the bundle however you can (see below). Then on env-B: ```bash nc-regression.sh \ --bundle-in /path/to/reg.tar.gz \ --out /tmp/reg \ --env-b $HCIROOT --site-b $HCISITE \ --route-test-cmd '' \ --phase env-b ``` That runs phases 4-6 (route_test on env-B with same inputs, diff each pair, master summary). ### Bundle transport options (pick whichever your network allows) | how | when | |---|---| | `scp` between the boxes | both boxes mutually SSH-reachable | | `scp` to your laptop, `scp` to env-B | you can SSH to each separately | | Private GitHub release / gist | both boxes can reach github.com but not each other | | Shared NFS / SMB mount | the boxes share a filesystem | | Box / SharePoint / S3 | enterprise common-storage | | USB stick / portable drive | nothing else works | | Tarball as email attachment | small bundles, both boxes have email | The bundle is plain `tar.gz` — nothing Cloverleaf-specific. Inspect it with `tar -tzf reg.tar.gz` to see what's inside before moving it. ### Lessons / refinements use the same pattern Larry on a client captures lessons locally (`/lesson`, lesson_record tool). You export the lesson bundle with `lib/lessons.sh export` and paste it back to home-Larry (the dev-machine session you have with me). Same model: local capture, manual transport, central merge. No direct peer protocol. --- ## Regression testing — end to end (`lib/nc-regression.sh`) Full Example 6 orchestrator. Six phases: discover → sample → route-test A → route-test B → diff → summary. ```bash # Phase-by-phase walk through (Bryan's house pattern) # Phase 1+2: discover inbounds and sample messages from env-A only lib/nc-regression.sh \ --scope site \ --env-a /opt/cloverleaf/test/integrator --site-a adt \ --env-b /opt/cloverleaf/prod/integrator --site-b adt \ --out /tmp/reg-2026-05-26 \ --count 10 \ --phase 2 # Inspect what would be sampled (dry-run) lib/nc-regression.sh --scope site --env-a /test --env-b /prod \ --site-a adt --site-b adt --out /tmp/reg --count 10 --phase 2 --dry-run # Full run — needs Cloverleaf route_test command supplied: lib/nc-regression.sh \ --scope site --site-a adt --site-b adt \ --env-a /opt/cloverleaf/test/integrator \ --env-b /opt/cloverleaf/prod/integrator \ --out /tmp/reg-2026-05-26 \ --count 10 \ --route-test-cmd 'cd {HCIROOT}/{HCISITE} && . ./.profile && {THREAD} route_test {INPUT} && cp *.out.* {OUTPUT_DIR}/' \ --phase all # Just diff existing outputs (you ran route_test manually before) lib/nc-regression.sh --scope site --site-a adt --site-b adt \ --env-a /opt/cloverleaf/test/integrator \ --env-b /opt/cloverleaf/prod/integrator \ --out /tmp/reg-2026-05-26 \ --phase 5 # Other scopes --scope thread:ADTto_3m # one thread --scope threads:ADTto_3m,MFNto_3m,DFTto_3m # specific list --scope server # every inbound in every site under HCIROOT ``` Output tree: ``` /tmp/reg-2026-05-26/ ├── inbounds.txt # the scope ├── inputs/.msgs # sampled inputs (1 per inbound) ├── outputs/env-a//... # env-A route_test outputs ├── outputs/env-b//... # env-B route_test outputs (using same inputs) ├── diff/..md # per-pair hl7_diff report ├── diff/_index.md # diff summary table └── regression-summary.md # master report ``` Tip: if env-B is remote, pass `--env-b-host --env-b-user ` and Phase 4 scp's inputs over before invoking route_test there. Or run on env-B separately and skip Phase 4 with `--phase 5` for diff-only. --- ## Reverse SSH tunnel (`larry-tunnel.sh`) If you want a home Larry to SSH into the client box (when client → outbound SSH is allowed): ```bash # Zero-config: serveo.net (third-party, NOT for sensitive sessions) larry-tunnel.sh --serveo # Your own hop (needs hop sshd configured with GatewayPorts) LARRY_HOP_USER=larry-tunnel \ LARRY_HOP_HOST=bjnoela.com \ LARRY_HOP_KEY=~/.ssh/id_ed25519 \ larry-tunnel.sh # Inspect / stop larry-tunnel.sh --status larry-tunnel.sh --stop ``` --- ## PHI handling — sanitize / desanitize (`lib/hl7-sanitize.sh`, `lib/hl7-desanitize.sh`) When working with prod data, tokenize PHI fields BEFORE they reach the API. ```bash # Sanitize a file: replaces PHI fields with [[CATEGORY_NNNN]] tokens. # Lookup table at ~/.larry/sanitize/lookup.tsv (mode 0600, never leaves the box). lib/hl7-sanitize.sh /opt/cloverleaf/.../some.hl7 > /tmp/sanitized.hl7 # Pipe an entire smat-dump through sanitize: lib/nc-msgs.sh ADTto_3m --limit 100 --format raw \ | lib/hl7-sanitize.sh > /tmp/sanitized-batch.hl7 # Strict mode also tokenizes unknown Z-segments wholesale: lib/hl7-sanitize.sh --strict ./msg.hl7 > /tmp/sanitized.hl7 # See the current lookup table (PHI is here — DON'T share): lib/hl7-sanitize.sh show-table # Count entries: lib/hl7-sanitize.sh count # Clear the table (asks for confirmation): lib/hl7-sanitize.sh clear-table # Tokenize a single value (used by Larry's {{phi:...}} preprocessor): lib/hl7-sanitize.sh tokenize-value --category MRN 12345 # → [[MRN_0001]] # Detokenize a single token: lib/hl7-sanitize.sh detokenize-value "[[MRN_0001]]" # → 12345 # Desanitize a whole document (e.g. view Larry's tokenized output unmasked, locally): cat larry-output.txt | lib/hl7-desanitize.sh | less # Quick token lookup: lib/hl7-desanitize.sh --token "[[NAME_0042]]" # Override default PHI rules (rule file format: SEG|FIELD|CATEGORY per line) lib/hl7-sanitize.sh --rules-file /tmp/my-rules.txt /tmp/msg.hl7 ``` ### Inside Larry (the REPL) ``` you> /phi 5720501458 phi> [[MRN_0001]] (use this in your next prompt) you> find messages for {{phi:MRN:5720501458}} in last 3 days phi> {{phi:MRN:5720501458}} → [[MRN_0001]] (the actual prompt sent to Anthropic has [[MRN_0001]] — the original MRN never leaves the box) you> /unmask [[NAME_0042]] unmask> [[NAME_0042]] → MORRIS^SALLY^^^... (local only; never sent to API) you> /tokens (prints the full PHI ↔ token lookup table — local terminal only) ``` PHI inline syntax in any prompt: - `{{phi:VALUE}}` — tokenize before send; auto-detects category (matches existing entries) - `{{phi:MRN:12345}}` — explicit category=MRN (matches sanitized data) - `{{phi:NAME:JOHN SMITH}}` — explicit category=NAME ### Default PHI rule set Fields tokenized by default (override with `--rules-file`): ``` PID.2..7, .9, .11, .13, .14, .18, .19, .20, .21, .29, .30 (patient IDs, name, DOB, address, phone, account, SSN, license) PV1.7, .8, .9, .17, .19, .50, .52 (providers, visit number) NK1.2, .3, .4, .5, .6, .16 (next of kin) GT1.3, .4, .5, .6, .7, .11, .12, .19 (guarantor) IN1.16, .17, .18, .19, .20, .36, .49 (insurance) OBR.10, .16, .32 / OBX.16 / DG1.3, .4 / ORC.10, .12 (orders/observations) ``` ### Limitations (read these) - **Your typed prompt can still leak PHI** if you don't use `{{phi:…}}` markers. Be deliberate. - **Custom Z segments** aren't tokenized unless `--strict` is passed (which then redacts unknown Zs wholesale). - **Free-text fields** (OBX.5 narratives, comments in NTE segments) can contain PHI in prose form. Default rules don't tokenize OBX.5; add it via `--rules-file` if your shop carries PHI in lab narratives. - **Repetitions** (`~`-separated within a field) are tokenized as one value, not per-rep. Adequate for most analysis. - **The lookup table at `~/.larry/sanitize/lookup.tsv` contains real PHI.** Mode 0600, never sent anywhere by these scripts, but it's still on disk. Wipe with `clear-table` before shipping the box anywhere. --- ## Quick recipe: "I have to do X without internet" | Task | Command | |---|---| | "what threads are here?" | `lib/nc-parse.sh list-protocols $HCISITEDIR/NetConfig` | | "find threads named *3m*" | `lib/nc-find.sh --name 3m --format table` | | "where does d_foo live?" | `lib/nc-find.sh --where d_foo --format table` | | "what feeds d_foo?" | `lib/nc-parse.sh sources $HCISITEDIR/NetConfig d_foo` | | "what does d_foo route to?" | `lib/nc-parse.sh destinations $HCISITEDIR/NetConfig d_foo` | | "what xlates does d_foo use?" | `lib/nc-parse.sh xlate-refs $HCISITEDIR/NetConfig d_foo` | | "find messages for MRN X" | `lib/nc-msgs.sh d_foo --field PID.3=X --format text` | | "diff this interface across two envs" | `lib/nc-diff-interface.sh --interface NAME --left A/NC --right B/NC --depth 1 --out out.md` | | "generate jump threads for a migration" | `lib/nc-make-jump.sh ... --inbound X --new-host Y --jump-port Z --out-prefix /tmp/jump` | | "insert a new protocol with rollback" | `lib/nc-insert-protocol.sh insert NC /tmp/block.tcl` then `larry-rollback.sh --target NC` if needed | | "what changes did I make recently?" | `larry-rollback.sh --list` | | "undo my last change" | `larry-rollback.sh --last 1 --dry-run` then `--last 1 --yes` | | "document a system" | `lib/nc-document.sh --name PATTERN --out FILE` | | "full regression test between two envs" | `lib/nc-regression.sh --scope site --site-a SA --site-b SB --env-a EA --env-b EB --out DIR --count N --route-test-cmd '...' --phase all` | --- ## Where to look when something breaks - `~/.larry/sessions/.log.md` — every Larry session is logged as markdown. - `~/.larry/journal//manifest.md` — every journaled write in that session, with diffs. - `~/.larry/journal/index.tsv` — flat index of every write across all sessions. - `~/.larry/.env` — your API key (if using API-key auth). - `~/.larry/.oauth.json` — OAuth tokens (if using subscription auth). - `~/.larry/agents/*.md` — the personas loaded into Larry's system prompt. Editable; reloaded each launch. All lib/ scripts accept `--help` (or `-h`) to print usage.