Scripts

Standalone tools that ship with Soma — codebase navigation, memory tracing, session focus, doc scraping, and more.

Standalone bash tools for Soma. Run from the command line — no agent session needed. Your agent also uses these during sessions. 20+ free scripts ship with the agent + 5 Pro scripts as compiled .js; more are available via soma hub install script <name>. Run soma --help scripts to see what’s installed.

Bundled Scripts

Installed to .soma/amps/scripts/ (or available via your global soma CLI). All ship with the agent — no hub install needed. soma-theme.sh is a shared dependency sourced by other scripts; not run directly. Use soma tool to introspect the agent-side tool surface (separate from these CLI scripts).

soma code — hub

Fast codebase navigator. Maps file structure, finds patterns, classifies references. Works with TypeScript, Python, Rust, Go, Bash, CSS, and more.

soma code map <file>                   # function/class index with line numbers
soma code find <pattern> [path] [ext]  # structured grep with file:line format
soma code refs <symbol> [path]         # all references, classified as DEF or USE
soma code lines <file> <start> [end]   # show exact lines
soma code replace <file> <ln> <old> <new>  # line-specific text replace
soma code structure [path]             # file tree with sizes
soma code tsc-errors [path]            # TypeScript errors with code context

Use map before editing any file — it gives you the function index so you know where to make changes.

📖 Full guide: Code Navigator — per-command docs, examples, why it exists, troubleshooting.

soma focus — hub

Seam-traced boot priming. Run before starting a session to focus the agent on a specific topic. Traces the keyword through memory, scores relevance, and generates heat overrides so the right muscles, protocols, and MAPs load.

soma focus <keyword>       # set focus — next soma boot is primed
soma focus show            # show current focus state
soma focus clear           # remove focus
soma focus dry-run <kw>    # preview without writing

# Example workflow:
soma focus runtime         # focus on runtime work
soma                          # start — agent wakes up primed for runtime

soma body

Body template inspector. Check health, list variables, preview the compiled system prompt.

soma body check                     # health report — missing vars, duplicates
soma body vars                      # all variables grouped by category
soma body map                       # template structure with var status
soma body render                    # full compiled system prompt

soma reflect

Parse session logs for observations, gaps, and recurring patterns.

soma reflect                        # observations from last 7 days
soma reflect --since 2026-03-12     # observations since date
soma reflect --gaps                 # gaps and recoveries only
soma reflect --recurring            # patterns mentioned 2+ times

soma plans

Plan lifecycle management. Plans rot — this tool helps you keep them alive.

soma plans status                   # active plan count + budget check
soma plans scan                     # list all plans with status
soma plans stale [--days N]         # find stale plans
soma plans archive <plan>           # archive a completed plan

soma session

Session maintenance — strip images, list sizes, analyze sessions.

soma session list                   # show all sessions with sizes per project
soma session stats                  # image count, dimensions for latest session
soma session strip-images           # strip base64 images from latest session
soma session strip --all            # strip images from all sessions
soma session strip --dry-run        # preview without modifying

When screenshots accumulate in a session, the JSONL file grows large and can hit API image limits. strip-images replaces image data with text placeholders so soma -c can resume cleanly.

soma-update-check.sh

Check installed content against the hub for newer versions.

soma-update-check.sh            # check for updates
soma-update-check.sh --json     # machine-readable output

soma children

Delegated-child monitor + spawner. Wraps tmux/cmux session management plus the ~/.soma/state/children.json registry that the in-session delegate(background:true) Pi tool writes.

soma children list                              # active children + cost/runtime
soma children spawn <role> "<task>"             # tmux-default; --cmux when available
soma children spawn <role> "<task>" --model haiku   # pin model
soma children watch [interval]                  # flicker-free dashboard
soma children tail <id>                         # tail a child's output
soma children kill <id>                         # terminate a child

Dashboard reads from children.json as the source of truth; pane scan is enrichment only. Hex IDs (child-xxxxxx) match the in-session tool’s shape so the agent and CLI views stay coherent.

soma tool

Discover what tools the agent has registered. Static parser — doesn’t start a session.

soma tool                       # list every tool with one-liner
soma tool <name>                # full guidance: description, promptSnippet, params
soma tool --extensions          # group by extension file

For the runtime view, call capabilities(op:'list') from inside a session.

soma new

Scaffold a new muscle or protocol with correct frontmatter — lowers the friction of crystallizing patterns. Idempotent: re-running on an existing name opens it in $EDITOR instead of clobbering.

soma new muscle <name>                          # .soma/amps/muscles/<name>.md
soma new protocol <name>                        # .soma/amps/protocols/<name>.md
soma new muscle <name> --global                 # ~/.soma/amps/...
soma new muscle <name> -d "description" -t trigger1,trigger2
soma new muscle <name> --no-edit                # skip $EDITOR

Templates live at templates/default/_muscle-template.md + _protocol-template.md — single source of truth for frontmatter conventions.

validate-content.sh

Validate AMPS content files before submitting to the community hub.

validate-content.sh protocols/my-protocol.md
validate-content.sh muscles/                    # validate all in dir

soma-theme.sh

Shared theming for all Soma scripts. Provides colors, header/footer helpers, and status functions. Sourced by other scripts — you don’t run this directly.

soma browser

CDP-based browser automation for testing and scraping (shell CLI).

Note: This is the shell-CLI counterpart. For agent-facing browser automation use soma:browser.* — the newer multi-browser configurable system that supports Chrome / Brave / Edge / Arc / Vivaldi / Chromium / Firefox via env + settings. See browser-setup.md for setup and cli-tools.md for the three-pattern model. The shell soma browser is kept for direct terminal use (bridge-proxied, hardcoded for Brave Beta on port 9333).

Advanced Scripts

A few heavier tools — concept tracing across memory, refactor analysis, doc scraping and remote repo inspection — are not part of meetsoma core. They will be offered separately; details when they are ready. The tools that would wrap them say so when they are not installed.

Hub Scripts (install with /hub install script <name>)

These scripts are available on the Soma Hub. Install any of them:

# Inside a Soma session:
/hub install script soma-query

# Or from CLI:
soma hub install script soma-query

soma query — hub

Unified search across your .soma/ workspace. Find content, check staleness, search sessions, trace connections.

soma query find "auth"              # search across all content + code
soma query list --type muscle       # list all muscles
soma query list --stale             # find stale content (30+ days)
soma query search --tags workflow   # search by tag
soma query search --deep "deploy"   # show TL;DR for matches
soma query sessions "typescript"    # search past session logs
soma query related my-muscle.md     # find linked docs via frontmatter
soma query impact settings.ts       # what references this file

soma-compat.sh

Compatibility checker — detects protocol/muscle overlap and conflicts. Produces a 0–100 score.

soma-compat.sh              # run compat check
soma-compat.sh --json       # JSON output

soma-snapshot.sh

Rolling zip snapshots of project directories.

soma-snapshot.sh . "pre-refactor"

soma-spell.sh

Spellcheck for AMPS content — catches common formatting and naming issues.

soma-spell.sh protocols/my-protocol.md
soma-spell.sh .soma/amps/    # check everything

git-identity-hook.sh

Git pre-commit hook that validates your git identity matches guard.gitIdentity settings.

soma-reflect-eco.py (cross-.soma ecosystem OSINT)

Not the same as soma reflect above — that one mines a single workspace’s session logs; this one walks EVERY .soma/.claude/.agents memory root AND every git repo below a directory, greps a topic across all of them, and merges the results into one dated timeline. Answers “what happened to X while I was away?” across a multi-project workspace in one call instead of manual per-project grepping. Also does contract-drift detection: same-relative-path body files that differ across sibling .soma roots (silent divergence — e.g. two projects’ _memory.md templates drifting apart with nothing catching it), plus missing-file gaps (a sibling has a file this root doesn’t).

soma-reflect-eco.py "auth flow"                              # timeline across every repo/memory root
soma-reflect-eco.py "X" --since 2026-07-01 --limit 50        # narrow by date
soma-reflect-eco.py --list-roots                             # map discovered memory roots + repos
soma-reflect-eco.py --drift                                  # body/*.md drift vs sibling .soma roots
soma-reflect-eco.py --drift --all-roots --drift-scope amps/muscles  # full sweep, different dir

Agent-side: soma:reflect.timeline, soma:reflect.roots, soma:reflect.drift.

soma-steno.py (deliberation + outcome telemetry)

Parses a session’s JSONL transcript for two signals. Hotspots: ranks turns by thinking-token spikes — each spike marks a place no muscle/trait existed yet to shortcut the reasoning; a recurring theme across spikes is a muscle candidate. Ratio: outcome-per-token — (writes + commits) / 10K tokens (output + thinking), logged automatically at every exhale via state-log.sh, making model-vs-model comparison objective instead of vibes.

soma-steno.py hotspots --top 8       # top 8 deliberation-heavy turns, ranked
soma-steno.py ratio                  # outcome-per-token for the current session
soma-steno.py both                   # both, default mode

Agent-side: soma:seam.hotspots (hotspots, on-demand); ratio runs automatically at exhale.

soma-hooks.sh (opt-in git hooks — changelog nudge + cycle trailers)

Installs a commit-msg hook so a commit can carry its own changelog entry. With it, a feat/fix commit that has no ### Added / ### Fixed block gets a reminder (a warning — your commit still goes through), and Soma-Session / Soma-Cycle trailers are stamped when those env vars are set.

soma-changelog.sh then lifts those blocks verbatim, so the sentence a user reads is written once — in the commit — instead of once there and again in CHANGELOG.md.

soma-hooks.sh status      # what is installed, and where it would go
soma-hooks.sh install     # write the hook
soma-hooks.sh uninstall   # remove only the hook this script wrote

It never writes core.hooksPath. That setting is a single path, so changing it would silently disable husky, pre-commit, lefthook or anything else you already use. The hook goes into whatever directory git already consults. If a commit-msg hook exists that this script did not write, it refuses and prints a one-line chain you can add yourself.

soma-cycle-shipped.py (derive a cycle’s shipped table from commits)

Commits stamped with Soma-Cycle: can be collected into a table, so a cycle’s record is derived rather than retyped.

soma-cycle-shipped.py <cycle-slug>                  # print the table
soma-cycle-shipped.py <cycle-slug> --write DOC.md   # fill the region between SHIPPED markers
soma-cycle-shipped.py <cycle-slug> --check DOC.md   # reconcile the doc against git; exit 1 on drift

--check reports commits that shipped without a row, and rows whose commit does not exist. It always prints how many commits carry no trailer at all — i.e. what it cannot see.

Building Your Own Scripts

Scripts in .soma/amps/scripts/ are discovered at boot and listed in the “Available Scripts” table. Build your own:

  1. Create a .sh file in .soma/amps/scripts/
  2. Add a header comment (first # comment line becomes the description)
  3. Add --help with usage examples
  4. Leave breadcrumbs: # Related: <muscle-name>, <other-script>

Your scripts get usage tracking automatically — the boot system records how often each is run in state.json.

#!/usr/bin/env bash
# my-tool.sh — one-line description shown in boot table
# Related muscles: incremental-refactor
# Related scripts: soma-code.sh

case "${1:-help}" in
  run)   echo "doing the thing" ;;
  help)  echo "my-tool.sh — usage: run" ;;
esac

When you do the same thing twice manually, build a script. The agent that builds its own tools gets faster every session.