UTENSIL
Analyze any git repository — dependencies, binary blobs, language
breakdown, history waste — in seconds.

Use Theme in the menu bar to switch between Classic, Graphite,
and Taipei Terminal. Taipei Terminal uses a rounded, pastel-forward
service-terminal look inspired by East Asian transit and kiosk
interfaces, including the Branches workspace panes, while keeping
accent text dark enough to stay readable on the light panels.
Your choice is remembered across launches.


INSTALL

  1. Drag Utensil.app to Applications (or run from anywhere).
  2. On first launch, macOS will block it (unsigned).
     Right-click the app > Open, then click Open in the dialog.

  Optional: install ripgrep for faster PII scanning and file search:
     brew install ripgrep
  The app works without it (falls back to grep), but ripgrep is
  significantly faster on large repositories. You can also install
  it later from Integrations > CLI Tools.

UNINSTALL

  Remove the installed app from Terminal with:
     utensil uninstall

  This removes the app bundle and /usr/local/bin/utensil. If Visual
  Studio Code's `code` command is available, Utensil also removes the
  VS Code extension. Local Keychain items and ~/Library state are
  left untouched.


GUI

  Double-click to launch. Drop a git repository folder onto the
  window, or use File > Open Repository (Cmd+O).

  Repo       Health warnings, language breakdown, dependency graph
             (DAG, radial, treemap, Mermaid), active branches,
             and code composition. The Composition tab shows a
             donut chart breaking down LOC between your code and
             each dependency, with a Runtime/All scope toggle and
             per-ecosystem confidence indicators. Architecture
             intelligence stays conservative on mixed repositories.
             It avoids forcing a single app label when the repo
             contains several ecosystems, but still shows verified
             networking and persistence signals. In monorepos,
             Overview lists the unique module app types that Phase 4
             detected, and the Modules tab shows per-module app-type
             badges when a module root matches a supported app tech.
  Status     Staged/unstaged files, inline diffs, commit.
             Image files show before/after previews in the differ
             when Utensil can load the old and new image content.
             Thumbnails show raster/vector type, dimensions, and
             file size. Click one
             to open a larger preview.
  Log        Branch-scoped commit history.
  Branches   Local and remote branches with heatmap. A collapsible
             Status panel at the top shows staged/unstaged files;
             click a file to see its diff. The panel auto-expands
             when the working tree is dirty.
             Worktree branches keep a folder marker even after
             merge-status checks finish loading.
             Merge-status checks show a tiny spinner while they run.
             If you drill into the commit log, your selected commit
             stays selected while those background branch checks finish.
             Nearby commit diffs are prefetched into memory, so
             selecting a different commit usually updates the differ
             immediately. Cache misses still flip the diff pane into
             a loading state instead of leaving the old diff on screen.
             Image files show before/after previews instead of a
             generic binary placeholder when preview data is available.
             Thumbnails show raster/vector type, dimensions, and
             file size. Click one
             to open a larger preview.
             Right-click for branch operations: create, checkout,
             rename, merge, rebase, push, pull, fetch, delete.
             Right-click tags for copy/push/delete (local) or
             copy/delete-from-remote (remote). Right-click stashes
             to apply, pop, copy message, or drop.
             Rebase divergence is detected automatically and shown
             as a single badge with safe force-push and reset options.
  CI/CD      Workflow Profile: infers whether you're a solo developer
             or a team, whether you push directly to main or use PRs,
             and whether releases are manual or automated. Shows a
             pipeline visualization and gives exactly one tailored
             recommendation for your next improvement. Also shows
             a 0–3 CI/CD maturity level, detected platforms, linting
             tools, and quality gates.
  Integrations
             Two tabs: LLMs (Claude + Ollama) and Credentials
             (GitHub token, Utensil account, App Store Connect,
             Jira). View, add, and remove access tokens. A global
             "Preferred AI Provider" picker lets you choose between
             Ollama, Claude, and OpenAI for most AI features.
             Release notes use Claude Opus via the Claude CLI
             first. If Claude is unavailable or returns an error,
             distribute.sh falls back to Codex CLI (default model:
             o3); in that fallback path, commit subjects are sent to
             OpenAI. The in-app draft and the "Utensil release-notes"
             subcommand use Claude only and do not fall back. The
             OpenAI card also shows which account the Codex CLI is
             signed into and warns when that detected login appears
             out of sync with your AI policy. The Claude card includes
             a trust shield that evaluates training policy against
             your ai-policy.yml.
  Security   Queries OSV.dev for known vulnerabilities in your
             dependencies. Enriches with EPSS exploit likelihood
             scores and CISA KEV (Known Exploited Vulnerabilities)
             data. Filter by severity, depth (direct vs transitive),
             scope (runtime vs dev/build), ecosystem, and exploited
             status. Each vulnerability shows an urgency tier
             (Act now / Attend / Track). Reachability uses the
             workflow-facing labels Reachable, No reachable path
             observed, and Reachability unknown. JSON output emits
             observation-scoped reachability evidence with limitations
             text for supported ecosystems. Visualizations tab shows
             attack path graph and asset criticality treemap.
             Overview tab includes risk heatmap and exposure trend.
  Sensitive Data
             Dedicated secrets/PII triage view for the current repo.
             Shows the sensitive-data verdict, a determinate
             rule-progress bar while scanning, per-rule findings,
             sample evidence, and an action to open or create
             `.utensil/pii-suppressions.txt` for recurring
             false positives. Marked Under construction during
             alpha so users know coverage is still evolving.
  Licenses   Dependency license compliance audit. "See also: AI
             Governance" links to the AI Compliance tab for policy
             cross-reference. Declares your distribution intent
             (commercial/internal/open source) and evaluates every
             dependency's license against it.
             Scans resolver-provided local source directories first,
             then falls back to repo-root package directories
             (node_modules, Go vendor, Ruby vendor/bundle, PHP vendor,
             Python venv, Debian packaging) and SwiftPM DerivedData
             before using version-aware registry metadata and the
             GitHub API.
             Exported licensing bundles can also include standalone
             legal review findings when evidence does not map cleanly
             to a dependency row.
             Shows flagged/warning/compatible/unknown groupings and
             a De Facto License card showing the union of all
             obligations across the full dependency chain.
  Portfolio  Cross-repo vulnerability intelligence. After scanning
             multiple repos, see shared vulnerabilities across repos,
             fix drift (repos that upgraded vs those that didn't),
             and remediation priorities ranked by cross-repo impact.
             Data stored locally at ~/.config/utensil/portfolio.json.
             CLI: utensil portfolio list|report|drift|remove.
  Navigation Use the single grouped sidebar to move between the main
             work areas: Codebase, Risk, Compliance, Delivery, AI,
             People, Portfolio, and Connections. When a repository is
             open, a shared header spans the top of the window above
             both sidebar and content and includes quick buttons for
             Branches: Diff and Branches: Remotes.
             On the Branches page, Cmd-D toggles between the default
             remote-focused view and the full developer-style branches
             workspace.
             Sensitive Data is a dedicated review surface for
             secrets/PII findings. It shows a determinate rule-progress
             bar while scanning, distinguishes lower-confidence review
             matches from higher-confidence secret findings, and lets
             you inspect evidence or manage suppressions.
             In Vetting dependency mode, the shared Own repo / Vetting
             dependency pill stays in a consistent top-right location
             across AI, Security, and CI/CD so the framing changes
             without the control moving around the screen.
             A Priorities tab shows a cross-domain Eisenhower matrix
             (urgency × impact) and ranked action list aggregating
             vulnerabilities, license issues, team risks, and more.
  AI         Four-tab AI page with a mode pill that lets you switch
             between "Own repo" (auditing your own project) and
             "Vetting dependency" (evaluating a repo you're
             considering as a dependency).

             Readiness — detects AI tools configured in the repo
               (CLAUDE.md, Copilot, Cursor, Ollama, MCP, etc.) and
               shows a 0–3 maturity level. Advice adapts to mode:
               setup guidance (MCP, Aider) is shown for your own
               repo but hidden when vetting.
             Compliance — sovereignty-aware compliance view:
               Data Sovereignty — scans the dependency tree for AI
                 SDK packages (openai, anthropic, langchain, etc.)
                 and checks data posture policy compliance.
               Code Sovereignty — shows repo visibility, AI config
                 file count, and per-tool annotations. Each detected
                 AI tool gets a plan picker with provider-specific
                 tiers (e.g. Claude: Free/Pro/Team/Enterprise).
                 Commercial tiers auto-show training status;
                 consumer tiers show an "Opted out?" pill.
               Policy Compliance — maturity level, forbidden tools,
                 required files, and review gate checks.
               All framing adapts to the mode: imperative when
               auditing your own repo, informational when vetting.
             Toolchain — recommends which tools to adopt based on
               your policy's data posture and maturity target.
               Hidden in vetting mode (can't add tools to someone
               else's repo).


CLI

  ./Utensil.app/Contents/MacOS/Utensil
  ./Utensil.app/Contents/MacOS/Utensil /path/to/repo
  ./Utensil.app/Contents/MacOS/Utensil /path/to/repo --summary
  ./Utensil.app/Contents/MacOS/Utensil /path/to/repo --json
  ./Utensil.app/Contents/MacOS/Utensil /path/to/repo --mermaid
  ./Utensil.app/Contents/MacOS/Utensil /path/to/repo --json --license-audit
  ./Utensil.app/Contents/MacOS/Utensil /path/to/repo --json --remediation-plan
  ./Utensil.app/Contents/MacOS/Utensil portfolio list
  ./Utensil.app/Contents/MacOS/Utensil portfolio report [--json]
  ./Utensil.app/Contents/MacOS/Utensil portfolio drift [--json]
  ./Utensil.app/Contents/MacOS/Utensil portfolio remove /path/to/repo
  ./Utensil.app/Contents/MacOS/Utensil --help

  Dependency outputs exclude Xcode build targets (`xcodeproj:` nodes).
  They describe project structure, not package dependencies.
  For monorepos, text output adds a Module App Types section and
  JSON output emits a `moduleRepoTypes` object keyed by repo-relative
  module path.
  Reachability JSON emits a top-level `reachability` object with
  observation-scoped summaries, evidence payloads, and limitations
  text for supported ecosystems.
  Text and JSON reports include the detected project license without
  requiring `--license-audit`.
  `--remediation-plan` is opt-in and only has an effect with `--json`.
  It runs bounded sandbox simulations for supported JavaScript package
  managers, compares the resolved dependency tree before and after each
  candidate change, and emits a top-level `remediationPlan` object. It
  does not edit the repository being scanned.
  `--license-audit` and `--full` run the same license-audit path in
  the SwiftPM CLI on macOS and Linux. License audit entries in JSON
  preserve dependency id, pinned version, and primary scope when
  that audit data is present. Local license resolution prefers
  resolver-stamped source directories before repo-root scans and
  SwiftPM DerivedData. GitHub fallback metadata is cached locally by
  canonical repo identity so repeated scans can reuse prior public
  results and avoid duplicate GitHub license lookups when possible.
  PyPI metadata can also normalize narrow package-specific full-text
  declarations and compatible permissive archive-text matches when
  those can be safely tied to the package.
  Before a batch scan, run `Utensil cache prewarm --urls-file <path>
  [--json]` to seed that cache from a file with one GitHub repository
  URL per line.
  The Licenses tab and native licensing exports both surface
  structured patent-grant metadata for the project and each component
  when Utensil models it, including scope, termination triggers, and
  license-section citations for licenses such as Apache-2.0,
  GPL-3.0, LGPL-3.0, AGPL-3.0, and MPL-2.0.
  Dependency graph JSON also includes a scopes array for packages
  that appear in more than one role.


UPDATES

  Utensil checks for updates on every launch. When a new version is
  available, the app displays an Install button. Click it to download
  and install the update automatically — the app restarts on its own.


REQUIRES

  macOS 14.0+ (Sonoma or later)
