enigma-cli

Everything you need to work with a coding agent, in one command. enigma installs a shared set of engineering policy skills into the agents you actually use (Claude Code, OpenAI Codex, opencode) and sets up portable git security hooks that block secrets, .env files, and dependency dirs from being committed.

Install

One command, no global install, no prompts - deploy the skills to every supported agent at user level:

npx enigma-cli@latest install --all --yes

Or install the command and pick interactively:

npm install -g enigma-cli      # provides the `enigma` command
enigma                         # interactive hub: pick what to set up

That first install is the only one you ever need to run by hand: afterwards, launching a tool through enigma (e.g. enigma claude) auto-syncs the deployed skills and memory with the installed package version (see Auto-sync).

Requirements

Minimum: Node.js >= 18 (with npm), Git and at least one coding agent. Recommended: add Claude Code, the GitHub CLI, Bun and Warp.

Details - what each one is for

Minimum

	>= 18, ships with npm - installs and runs the enigma CLI
	powers the security hooks and the commit guard
	at least one of Claude Code, OpenAI Codex or opencode - the skills need a home

Recommended

Everything in Minimum, plus:

	the agent enigma is most battle-tested with
	gh commits go through the same hooks, and enigma issue opens prefilled reports
	only needed to build or contribute from source
	a modern terminal where the hub TUI shines

Commands

enigma                 Interactive menu: choose features to set up
enigma install         Install/update agent skills
enigma security        Set up git security hooks in the current repo
enigma guard [--all]   Run the commit guard (staged files, or all tracked)
enigma config [k v]    Show or set runtime toggles (e.g. config commit-emoji off)
enigma <tool> [acct]   Launch claude | codex | opencode with an account
                       (resolution: explicit > active profile > tool active);
                       auto-syncs deployed skills first
enigma account ...     Manage per-tool accounts (list/add/use/login/remove)
enigma profile ...     Group one account per tool (list/add/use/set/unset/remove)
enigma skills ...      List skills and manage discards (list/discard/restore)
enigma seal            Maintenance: (re)compute skill content hashes
enigma check           Integrity gate: verify skills are well-formed and sealed
enigma help | version

Agent skills

Skills are authored once and deployed to every selected agent (no per-agent duplication). enigma install auto-detects which agents are installed (CLI on PATH or a config dir like ~/.claude, ~/.codex, ~/.config/opencode) and preselects them; --all targets every supported agent.

(--local installs into the current project instead.)

Don't want one of the skills? Discard it from the hub's install panel (the SKILLS section lists every skill; unchecking one discards it) or with enigma skills discard <name>: it is removed from every agent and skipped by future installs, updates and auto-syncs until you restore it with enigma skills restore <name>.

Slash commands

enigma install also deploys reusable slash commands to every selected agent (a full install only - --skills-only / --memory-only skip them). Each command is authored once and copied verbatim to the agent's command directory, where the file name becomes the command.

(--local installs into the project's .claude/commands/ and .opencode/command/. Codex has no project-local prompt directory, so it only receives commands at global scope.)

Commands are enigma-managed: if a same-named command already exists and is not enigma's, it is replaced so enigma's command always wins the name. A command you have not changed is left untouched; auto-sync keeps it current on every launch.

/improve

Two modes in one command. Implement mode edits a focused area directly; Advisor mode (adapted from shadcn/improve, MIT) is strictly read-only and writes self-contained implementation plans into plans/ for another (cheaper) agent to execute.

The mode is resolved from the arguments: an advisor keyword (audit, quick, deep, branch, next, plan, review-plan, execute, reconcile) selects Advisor mode; otherwise an area token selects Implement mode. A bare security or performance runs Implement mode (edits code) for backward compatibility - to audit those read-only instead, prefix an advisor keyword (audit security, quick perf). With no argument (or an unknown one) it prints both usages and stops.

Implement mode (/improve <area>):

It detects the project stack first, reuses existing code, applies the smallest change, follows any matching policy skill, and verifies with the project's build/lint/test before reporting.

Advisor mode (read-only; writes only to plans/):

Advisor mode never modifies source code, never mutates the working tree, and never reproduces secret values. Each plan is self-contained, stamps the commit it was written against, and carries machine-checkable done criteria and STOP conditions so a weaker executor can run it without this session's context.

Auto-sync on launch

After the first enigma install, you never need to run it again: whenever you launch a tool through enigma (enigma claude, enigma account run work), enigma first compares the deployed skills/memory against the installed package version and silently refreshes anything that changed (new skills, updated versions, removed skills, memory-file edits). On by default; opt out with:

enigma config auto-sync off

Auto-sync is deliberately conservative:

• It only touches agents/scopes that already have a deployment - it never performs a first install (that stays your explicit enigma install).
• Skills you modified locally are never overwritten (same rule as --keep-modified).
• The memory file (CLAUDE.md / AGENTS.md) is only rewritten when it is byte-identical to what enigma last wrote (tracked in ~/.enigma/state.json) - a file you authored or edited is never touched.
• A sync failure never blocks the launch; the tool starts anyway.

Auto-lint on edit

Opt-in. When on, enigma autonomously installs @enigmax/linter into a managed dir (~/.enigma/linter, in the background) and wires a post-write hook into each agent, so every file an agent writes is linted the moment the edit finishes:

enigma config auto-lint on    # installs the linter and wires the hooks
enigma config auto-lint off   # removes the hooks

The hook is designed for minimum token cost: it auto-fixes the safe formatting rules (whitespace, blank lines, final newline) in place, and surfaces only the unfixable findings (hardcoded secrets, URL imports, style issues that need judgement) back to the agent. A clean file produces no output at all - zero added tokens.

• Claude Code: a PostToolUse hook in settings.json (matcher Edit|Write|MultiEdit|NotebookEdit). Unfixable findings come back via the hook's stderr, which Claude feeds to the model.
• opencode: an auto-loaded plugin in ~/.config/opencode/plugins/ whose tool.execute.after runs the same check and appends the findings to the tool output the model sees.

Both invoke one shared runner (~/.enigma/hooks/lint-hook.mjs) that resolves the managed linter and no-ops cleanly until the background install lands (self-healing). The wiring is mirrored into managed account config dirs on sync, like the other managed settings. Default: off (it changes agent behavior and installs a package, so it stays an explicit choice).

Git security hooks

enigma security drops a portable, dependency-free commit guard into any repo: it copies guard.mjs into the repo's .githooks/, writes a cross-platform pre-commit shim and a toggle config, and points core.hooksPath at it. Commit .githooks/ so the team inherits it. Because it runs on git commit, it also covers commits made through the GitHub CLI (gh).

On every commit the guard, OS-agnostically:

• Blocks committed secrets (API keys, tokens, private keys).
• Blocks .env / .env.local (allows *.example / *.sample / *.template).
• Blocks dependency/cache dirs (node_modules, __pycache__, virtualenvs).
• Warns on generated dirs (dist, build, .next, coverage), log/OS-junk files, and files over 5 MB.

Each protection is individually toggleable (saved to .githooks/enigma-guard.json). Bypass once with git commit --no-verify.

Multiple accounts and profiles

Work across separate workflows with different accounts per tool - for example your company Claude Code account and your personal one - keeping each fully isolated and switching between them without ever logging out. Each account has its own credentials, session, and history, so client work never mixes with personal projects. Supported tools: Claude Code (CLAUDE_CONFIG_DIR), OpenAI Codex (CODEX_HOME) and OpenCode (a private XDG_DATA_HOME / XDG_CONFIG_HOME pair per managed account; its default account keeps your real environment untouched).

This is for legitimate, professional account separation (one account per employer/context, as many organizations require). It is not a way to evade usage limits or Anthropic's terms - each account still authenticates as itself and is subject to its own limits. Use the account that each piece of work belongs to.

Claude Code reads its credentials and session from the directory in CLAUDE_CONFIG_DIR (default ~/.claude), so each profile just needs its own directory. Rather than hand-editing per-shell aliases, enigma launches Claude for you with that variable set - the same command on macOS, Linux and Windows.

enigma account add work --login   # create 'work' and run /login to authenticate
enigma account add personal       # create 'personal' (log in later)
enigma account add acme -t codex  # create a Codex account
enigma account list               # show all accounts (active one marked *)
enigma claude work                # run Claude Code as 'work'
enigma codex acme                 # run Codex as 'acme'
enigma account use personal       # make 'personal' the active account
enigma claude                     # run the resolved account (profile > active)
enigma claude work -- --version   # forward args after -- to the tool
enigma account rename work corp   # rename an account (its config dir moves)
enigma account remove work        # delete an account and its config dir

Your existing ~/.claude / ~/.codex / opencode setup is always available as each tool's built-in default account (never deleted). New accounts live under ~/.enigma/<tool>/<name>/. Bare claude / codex / opencode commands keep using your real environment as before.

Managed accounts inherit your enigma setup automatically: because the tool reads everything from the account's config dir, enigma deploys the skills and memory file into it (seeded on account add and on launch) and mirrors the enigma-managed native settings from your default account on every launch - Claude's permission bypass, attribution overrides and statusline, Codex's approval_policy/sandbox_mode, opencode's "*": "allow" permission. Turning a knob off on the default account propagates too; per-account manual edits to those specific knobs are overwritten on the next launch, while every other account setting (theme, custom statusline, extra permissions) is left untouched.

Profiles (one account per tool)

A profile pins one account per tool under a single name - e.g. profile work = Claude Code work + Codex acme. While a profile is active, enigma <tool> launches that profile's account for the tool (explicit account arguments still win; unmapped tools fall back to their own active account):

enigma profile add work                 # create the profile
enigma profile set work claude work     # pin claude account 'work'
enigma profile set work codex acme      # pin codex account 'acme'
enigma profile use work                 # activate (enigma claude/codex now use it)
enigma profile list                     # profiles + mappings (* = active)
enigma profile rename work corp         # rename a profile (mappings stay)
enigma profile use none                 # deactivate

From the hub TUI (enigma), the Accounts panel lists every tool's accounts - with the signed-in identity (email for Claude/Codex, connected providers for OpenCode) - and lets you add (a), set active (enter), connect/log in (c), rename (r), or remove (d). Adding first asks which tool with a searchable selector (type to filter, like opencode's model picker), then the account name, then offers to connect right away. The Profiles panel manages profiles end-to-end: enter switches the active one ((none) deactivates), a creates one, e edits its mappings (searchable tool selector, then a searchable account selector including (unpin)), r renames it, and d removes it (accounts are kept).

GitHub CLI telemetry (default off)

If the GitHub CLI (gh) is installed, enigma install disables its usage telemetry (gh config set telemetry disabled). This is pure privacy upside - telemetry is usage analytics only (command, flags, OS/version, device ids) and no gh feature depends on it - and it also avoids a known Windows bug where the detached gh send-telemetry subprocess spawns tzutil.exe without hiding its window, flashing a terminal on gh invocations (cli/cli#13354). Re-enable any time:

enigma config gh-telemetry on     # restore gh's default
enigma config gh-telemetry off    # disable again

Claude feedback survey (default off)

When Claude Code is a target, enigma install disables the periodic "How is Claude doing?" session-quality survey by setting env.CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY to "1" in Claude's settings.json. It is a recurring prompt with no functional value, so it is off by default. Re-enable any time:

enigma config claude-survey on        # restore Claude's survey
enigma config claude-survey off       # disable again
enigma config claude-survey off -g    # global (~/.claude/settings.json)

Commit emojis

By default the policy skills make commit subjects carry a leading type emoji (one per subject, e.g. for feat/fix); code, prose, and PR text stay emoji-free. The convention and its type-to-emoji map live in the git-policy skill. Opt out per repo or globally:

enigma config commit-emoji off       # disable (writes .enigma.json)
enigma config commit-emoji on        # re-enable
enigma config commit-emoji off -g    # global (~/.enigma.json)

Precedence: built-in default (on) -> ~/.enigma.json -> repo .enigma.json.

Parallel sub-agents

The memory file always tells agents to break long or complex tasks into smaller subtasks and complete them incrementally. The parallel part - delegating independent subtasks to sub-agents that run at the same time to finish faster - is opt-in, because spawning sub-agents multiplies token cost:

enigma config parallel-subagents on        # add the parallel section to the memory file
enigma config parallel-subagents off       # remove it (default)
enigma config parallel-subagents on -g      # global (~/.enigma.json)

This toggle edits the deployed agent memory file (adds or removes the section), so restart Claude Code / Codex / OpenCode after changing it for the new session to pick it up. Subtask decomposition itself is always on and is never removed.

Token-efficient output

Optionally compress the agent's chat prose to cut output tokens while keeping full technical accuracy. Chosen at install or via config; off by default:

enigma config output-style lite     # professional terse (drop filler, keep grammar)
enigma config output-style full     # shorter, drops articles and uses fragments
enigma config output-style ultra    # telegraphic, maximum compression
enigma config output-style off      # back to full prose (default)
enigma install --output-style lite  # set it during install

on/off also work (on = full). Like the toggle above it edits the memory file, so restart your agent after changing it. Code, comments, commits, and PRs stay normal, the agent reverts to full prose for security warnings and other safety-critical replies, and the level is switchable mid-session by asking ("be more terse", "ultra", "normal mode").

Claude Code's status bar shows an [ENIGMA] badge at all times; while the mode is active it appends the level ([ENIGMA:FULL], [ENIGMA:LITE], [ENIGMA:ULTRA]). enigma wires this into settings.json during enigma install, only when you have no status line configured (it never replaces your own). If you upgraded the package, re-run enigma install once to wire it.

Minimal code (anti-overengineering)

The companion to token-efficient output: that compresses how the agent talks, this governs how it builds. It pushes the agent toward the laziest solution that works - YAGNI, the standard library and native platform features before custom code, one line before fifty. On by default at full:

enigma config minimal-code lite     # build what's asked, name the lazier alternative
enigma config minimal-code full     # YAGNI ladder enforced, shortest working diff (default)
enigma config minimal-code ultra    # YAGNI extremist, deletion before addition
enigma config minimal-code off      # opt out, no extra pressure
enigma install --minimal-code lite  # set a different level during install

on/off also work (on = full). Like token-efficient output it edits the memory file, so restart your agent after changing it. Security, input validation at trust boundaries, data-loss error handling, and accessibility are never simplified away. The full discipline lives in the anti-overengineering-policy skill, and the level is switchable mid-session by asking ("be more lazy", "full", "stop minimal-code").

For the on-demand passes, the anti-overengineering-review skill reviews a diff, audits the whole repo, or harvests the enigma: shortcut markers into a debt ledger - ask to "review for over-engineering", "audit the codebase for bloat", "what can we delete", or "list the deferred shortcuts". It emits a tagged list of cuts (stdlib/native/yagni/delete/shrink) with a net: -N lines score and applies nothing; correctness and security stay with the normal review.

Side-by-side "with vs without enigma" comparisons live in docs/examples/.

License

Apache-2.0.