alembic

Use Alembic when raw shell output is large enough to waste context or hide the real signal.

When To Use

• Long test runs, CI logs, stack traces, git diff, rg/grep output, watch output
• Questions that only need failures, filenames, risk signals, or a short state summary

When Not To Use

• Short output already easy to read
• Interactive or TUI commands
• Cases where exact raw formatting is the point

Helper Resolution

Use this order:

1. If alembic is already on PATH, use it. Prefer command -v alembic >/dev/null 2>&1 over which alembic, because some shells print "not found" text to stdout.
2. Otherwise, look for the first existing helper in these locations and use node <helper> ...:
   • ~/.codex/skills/alembic/runtime/bin/alembic.mjs
   • ~/.claude/skills/alembic/runtime/bin/alembic.mjs
   • ./tooling/alembic/bin/alembic.mjs
   • ./alembic/runtime/bin/alembic.mjs
   • ./plugins/alembic/skills/alembic/runtime/bin/alembic.mjs
3. When you probe manually in shell, check for existence with -e, not executability with -x, because the helper is a Node entrypoint and may not have the execute bit set.
4. A safe probe is:

if command -v alembic >/dev/null 2>&1; then
  echo alembic
elif [ -e "$HOME/.codex/skills/alembic/runtime/bin/alembic.mjs" ]; then
  echo "node $HOME/.codex/skills/alembic/runtime/bin/alembic.mjs"
elif [ -e "$HOME/.claude/skills/alembic/runtime/bin/alembic.mjs" ]; then
  echo "node $HOME/.claude/skills/alembic/runtime/bin/alembic.mjs"
elif [ -e "./tooling/alembic/bin/alembic.mjs" ]; then
  echo "node ./tooling/alembic/bin/alembic.mjs"
elif [ -e "./alembic/runtime/bin/alembic.mjs" ]; then
  echo "node ./alembic/runtime/bin/alembic.mjs"
elif [ -e "./plugins/alembic/skills/alembic/runtime/bin/alembic.mjs" ]; then
  echo "node ./plugins/alembic/skills/alembic/runtime/bin/alembic.mjs"
else
  echo missing
fi

5. If none of those exist, skip Alembic and work from raw output.

Usage Rules

• Use --level flame for normal reduced output, --level ember for one-line output, and --level ash to suppress success noise while still surfacing failures and prompts.
• Prefer --preset tests|actions|mcp|docker|k8s|safety|files|summary|logs|approval when one of the built-in output contracts already matches the task.
• Use --drop-level TRACE,DEBUG,INFO to remove noisy tagged log lines before reduction.
• Use --keep-level ERROR,WARN when the user wants only tagged high-severity log lines plus their immediate continuation lines.
• If both --preset and --question are present, --question wins.
• Prefer alembic exec --question "..." -- <command ...> for long-running commands when exit status matters.
• Prefer alembic benchmark exec --question "..." -- <command ...> when the user wants proof that Alembic is reducing a noisy workflow usefully on the current repo.
• Prefer alembic benchmark diff --base main --question "..." when the user wants to compare raw diff context versus Alembic on the current branch.
• Prefer alembic effort --format json --requested <level> "..." at prompt-submit or plan-start hook boundaries when you want a local effort recommendation.
• Prefer alembic hook-config show --host claude|codex or alembic hook-config set --host claude|codex ... when the user wants Alembic hook defaults persisted.
• Prefer alembic init for AGENTS.md rules and alembic init claude for CLAUDE.md rules when the user wants repo-local instructions that tell future agents when to use $alembic and when to run the effort heuristic.
• Prefer alembic benchmark effort --set smoke when tuning or validating the effort heuristic on the current repo.
• Add --verbose to benchmark only when the user wants artifact paths, timing, the wrapped command, or a raw preview for debugging.
• Use command 2>&1 | alembic "..." only when wrapping an existing one-liner is simpler.
• Ask fully explicit questions. Name the exact output shape you want.
• Answer from Alembic output first. Open artifactPath only if the reduced output is still insufficient.
• Alembic summarizes the provided output. It does not verify repo truth on its own.
• Alembic reduces wrappers, not requested facts.
• For MCP transcripts, preserve requested rows, fields, groups, filters, or JSON whenever the captured payload already contains that data.
• Alembic works well with noisy MCP-related output emitted by Claude Code or Codex, including terminal captures and agent-emitted JSONL mcp_tool_call events, but it does not launch MCP servers or control the protocol directly.
• If the task changes from summarization to diagnosis or root-cause analysis and a repo is available, reduce the noisy output first, then verify against local files before asserting causes.
• Alembic core is local and deterministic. Do not require network or API keys for the default path.

Examples

node /absolute/path/to/alembic-helper exec --level ash --preset tests -- npm test

node /absolute/path/to/alembic-helper benchmark exec --level flame --preset tests -- npm test

gh run view --log | node /absolute/path/to/alembic-helper --level ember --preset actions

cat mcp-trace.log | node /absolute/path/to/alembic-helper --level ember --preset mcp

docker build . 2>&1 | node /absolute/path/to/alembic-helper --level ember --preset docker --drop-level INFO,DEBUG

kubectl describe pod api-123 | node /absolute/path/to/alembic-helper --level ash --preset k8s --keep-level ERROR,WARN

node /absolute/path/to/alembic-helper benchmark diff --level ember --preset safety --base main

node /absolute/path/to/alembic-helper benchmark diff --level flame --preset safety --base main --verbose

node /absolute/path/to/alembic-helper effort --format json --requested high "Render four read-only cards in one desktop shell."

node /absolute/path/to/alembic-helper benchmark effort --set smoke

node /absolute/path/to/alembic-helper init

node /absolute/path/to/alembic-helper init claude

git diff -- src | node /absolute/path/to/alembic-helper --level ember --preset summary

node /absolute/path/to/alembic-helper --level ash --preset approval