Sphinx Agent

Local-first secret guard for terminal + AI workflows. Every byte that crosses the model, tool, or session boundary is scanned by Sphinx Secret Guard and plaintext secrets are replaced with $SPHINX_REF(NAME) references resolved from the local encrypted vault.

Install

pnpm install
pnpm -C packages/cli build
node packages/cli/bin/sphinx.mjs --help

Or link the bin globally:

pnpm -C packages/cli link --global
sphinx --help

Quick start

sphinx init                          # create encrypted vault
sphinx scan path/to/file             # find secrets in a file
sphinx scan path/to/dir              # recursively scan a directory
sphinx scan --replace --output clean.txt in.txt  # write sanitized copy
sphinx vault add NAME VALUE          # store a secret locally
sphinx config set provider anthropic # or: openai, openai-compatible, mock
sphinx workspace                     # show workspace context (git, pm, instructions)
sphinx doctor --strict               # diagnose setup; fail on invalid config
sphinx --print "explain this repo"    # one-shot agent output (json/stream-json available)
sphinx                                # interactive guarded agent REPL

Discovery

Every command group is introspectable for automation:

sphinx commands --json               # list top-level commands
sphinx commands --tree --json        # nested commands + subcommands
sphinx <group> commands --json       # subcommands for a group
sphinx tools schema --json           # MCP-compatible tool definitions

Providers

apiKeyRef accepts:

• env:NAME — read from environment variable
• vault:NAME — read from local vault (requires SPHINX_VAULT_PASSPHRASE)
• $SPHINX_REF(NAME) — same as vault:NAME

Built-in providers: mock, anthropic, openai, openai-compatible.

Guard principles

• Secret Guard sanitizes every message before it reaches any model.
• File tools are sandboxed to the current working directory (SPHINX_ALLOW_OUTSIDE=1 to override).
• Every tool call is appended to $SPHINX_HOME/audit.log (see sphinx audit tail).
• Approval flow gates writes, edits, and risky shell commands.

Ignoring paths

When scanning a directory, Sphinx reads a .sphinxignore file at the scan root. Each line is a glob (# comments allowed); matching files are skipped. node_modules and .git are always skipped, and binary files are detected and ignored.

# .sphinxignore
fixtures/**
*.min.js

Commands

| Command | Description | | --- | --- | | commands [--tree] | List Sphinx commands (optionally nested) | | help [name] | List commands grouped by kind, or describe one (--json) | | init | Create the encrypted vault | | scan <path> | Scan a file or directory for secrets | | vault add/get/list/rotate/path/rm | Manage local secrets (rotate changes the passphrase, path prints the vault location) | | run <cmd> | Run a command with Sphinx-sanitized output | | config set/get/unset/list/path/reset | Read or update CLI config (path prints config location) | | provider list/set/current/test | Manage AI providers | | approvals list/get/set | Manage approval mode | | doctor [--strict] | Diagnose Sphinx setup; strict mode fails on config issues | | session list/latest/show/search/export/diff/rename/fork/clear/delete | Inspect, search & manage sessions (export --output, diff, fork, clear --force) | | resume [id] | List resumable sessions or preview resume context (--continue/--resume) | | cost [model] | Show token totals and estimated cost for known model pricing | | statusline preview/tokens/set/reset | Customize REPL footer ({provider}, {model}, {guard}, {inputTokens}, {outputTokens}, {cost}) | | permissions ask/auto-read/auto-edit/full-auto | Manage approval mode (Shift+Tab cycles in REPL) | | plugins/plugin | Manage plugins + marketplaces (marketplace, browse, install, enable, disable) | | audit tail/stats/clear/path | Inspect the audit log (tail --tool/--failed/--since, stats, clear --force) | | tools list/schema/call/show | Inspect & invoke agent tools (schema = MCP, call runs a tool) | | workspace | Show workspace context | | mcp | Run as an MCP server over stdio or configure MCP client servers | | review [scope] | Agent review of current changes (staged, a ref, or a path) | | pr-comments [pr] | Agent fetches & summarizes PR review comments via gh | | commit | Agent creates a single git commit for current changes | | sphinx [--continue|--resume <id>] | Interactive guarded agent REPL | | --print/-p [--output-format text|json|stream-json] | One-shot agent prompt; persists a resumable session |

Each group also supports <group> commands [--json] for machine-readable subcommand discovery.

MCP server

sphinx mcp speaks JSON-RPC 2.0 over stdio (initialize, tools/list, tools/call, ping), exposing Sphinx's agent tools to any MCP client. Tool output is secret-sanitized, the cwd sandbox applies (SPHINX_ALLOW_OUTSIDE=1 to override), and destructive shell stays gated. Example client config entry:

{ "mcpServers": { "sphinx": { "command": "sphinx", "args": ["mcp"] } } }

License

Apache-2.0