AXEL Setup — Claude Code Power Configuration

AXEL = Autonomous eXcelsior Engineering Layer

A complete, production-grade configuration package for Claude Code that transforms it into a proactive engineering partner. Includes session persistence, automatic memory, proactive error resolution, a curated suite of specialized agents and slash commands, and a real-time usage monitor.

GSD is not vendored. get-shit-done installs and updates independently (npx get-shit-done-cc). AXEL consumes the live GSD skills/agents rather than bundling a frozen copy — see the CHANGELOG entry for 2026-06-02.

Philosophy: Excelsior

AXEL operates on the Excelsior principle — always beyond, always better, never stop at obstacles:

• Proactive resolution: When a command fails, AXEL investigates the root cause, attempts to fix it (start services, install deps, fix configs), and retries — before asking you
• Auto-verification: After non-trivial changes (3+ files), AXEL automatically launches a verification agent in the background
• Session persistence: Every session is summarized, key learnings are extracted to memory, and the next session starts with full context of what happened before
• Context awareness: Monitors context window usage and warns before it runs out
• Usage monitoring: Tracks token usage, cost, and rate limit consumption per session — live terminal dashboard and web dashboard at http://localhost:9119

Ecosystem Relevance

AI coding tools are moving from individual prompts into repeatable team workflows. AXEL exists to make those workflows easier to share, audit, and improve as open source infrastructure.

The project packages operational patterns that many engineering teams need when adopting Claude Code:

• Reproducible setup for hooks, commands, agents, skills, plugins, and team templates.
• Guardrails for risky agent behavior, including commit validation, context monitoring, and explicit subagent model routing.
• Session persistence and memory extraction so long running engineering work can survive context resets.
• Verification and review workflows for code changes, incidents, deploy checks, and multi repo coordination.
• Additive installation that preserves each developer's existing Claude configuration.

The goal is not to hide local preferences inside one private setup. The goal is to convert practical agentic engineering workflows into reusable tooling that other developers can install, inspect, adapt, and contribute back to.

Runtime Direction

AXEL is Claude Code-first by default. That stays true for the public package because the complete installer targets Claude Code hooks, commands, agents, skills, plugins, and ~/.claude conventions.

Codex and other agent runtimes are supported through explicit install targets, not by weakening the Claude Code path. The current non-Claude targets install portable AXEL assets only, without Claude hooks, plugins, settings, launchd agents, or GSD side effects.

npx axel-setup --target claude   # default
npx axel-setup --target codex    # experimental Codex adapter
npx axel-setup --target generic --output ./axel-runtime

See AXEL Multi-Runtime Roadmap for the adapter plan, compatibility rules, completed first slice, and remaining native runtime work.

Quick Start

The recommended install path is directly through npx:

npx [email protected] --dry-run --user-name "Your Name"

By default AXEL uses --profile core, a public safe Claude Code install that keeps conservative permissions and skips optional side effects such as plugin installation, usage monitor launchd setup, keybindings, and the external GSD installer. Use --profile personal or --profile full when you explicitly want the fuller local automation setup.

Alternatively, for a macOS one-line installer, use the pinned curl wrapper. It checks for Claude Code, jq, zsh, and Node before delegating to the packaged npm release:

curl -fsSL https://raw.githubusercontent.com/cveralyon/axel-setup/v0.4.0/install.sh | bash -s -- --dry-run --user-name "Your Name"

Before the first npm publish, use the same wrapper against the GitHub package source:

curl -fsSL https://raw.githubusercontent.com/cveralyon/axel-setup/main/install.sh | AXEL_SETUP_PACKAGE=github:cveralyon/axel-setup bash -s -- --dry-run --user-name "Your Name"

Use the GitHub-hosted entrypoint when you want the repo tip before a registry release:

npx github:cveralyon/axel-setup --dry-run --user-name "Your Name"

Or clone the repository:

git clone https://github.com/cveralyon/axel-setup.git
cd axel-setup
bash bootstrap.sh --user-name "Your Name"

Maintainer Publish Checklist

Run publish commands from the repository root, where package.json lives:

cd <repo-root>
npm whoami
npm run check
npm run publish:dry-run
npm publish --access public

From another directory, pass the package path explicitly:

npm publish <repo-root> --access public

Maintainer Release Automation

The repository includes a tag-driven npm release workflow in .github/workflows/release.yml. It is designed for GitHub Actions npm publishing with provenance.

Before the first automated release:

• Prefer npm Trusted Publishing for cveralyon/axel-setup and workflow file release.yml. npm requires the package to exist before npm trust can configure that relationship, so the first publish may still need an npm automation token as the NPM_TOKEN repository secret.
• Make sure the package version in package.json and the changelog entry are ready.
• Verify the package locally with npm run check and npm run publish:dry-run.

Release flow:

git tag v0.2.1
git push origin v0.2.1

The workflow installs shellcheck, shfmt, and npm 11, runs npm run check, then publishes only when the tagged version is not already on npm. With Trusted Publishing configured, GitHub Actions OIDC publishes without a long-lived token and npm generates provenance automatically. If NPM_TOKEN is present, the workflow uses it as a fallback with npm publish --provenance --access public. It rejects tags that do not match package.json version.

After a release, verify:

npm view axel-setup version
npm view axel-setup dist-tags --json
npm view axel-setup time --json

Rollback for a bad release is intentionally conservative: publish a fixed patch version. If users should stop receiving the bad version before the fix is ready, move the latest dist-tag back to the previous stable version:

npm dist-tag add [email protected] latest

Setup Hardening CLI Surface

The setup hardening release makes the published CLI easier to operate in CI, corporate environments, and third-party installs:

• --profile core is the default public safe profile for reusable Claude Code setup.
• --profile personal and --profile full opt into the fuller local automation footprint.
• --profile minimal for lean installs with a smaller default footprint.
• --skip-plugins, --skip-gsd, and --no-launchd so maintainers and CI can suppress optional side effects.
• --target claude|codex|generic so Claude Code stays the default while Codex and generic runtimes can receive portable AXEL assets.
• npx axel-setup doctor --target claude --home ~ to verify that an installation matches the shipped manifest and report missing files.
• npx axel-setup doctor --target codex --codex-home ~/.codex and npx axel-setup doctor --target generic --output ./axel-runtime for non-Claude installs.
• npx axel-setup diff --target <target> to audit installed files against the package.
• npx axel-setup review-upgrades --target <target> to inspect generated upgrade proposals before applying anything manually.
• npx axel-setup metrics [--json] to summarize context-budget, usage-monitor, and hook-harness impact signals without reading private local session data.
• npx axel-setup uninstall --target <target> to preview removals, then add --apply to remove only exact package matches.

Advanced: pass extra context so the Stop hooks personalize their prompts:

bash bootstrap.sh \
  --user-name "Emiliano" \
  --user-context "Backend engineer at Acme, Python specialist" \
  --language spanish

• --user-context gives the memory-extractor and session-summarize hooks a short self-description so their summaries frame decisions around your role. Defaults to a software engineer.
• --language tells the same hooks which language to respond in when they generate summaries (so non-English speakers get Spanish/French/etc. summaries back). Defaults to english.
• Both are optional and reversible — re-run the bootstrap with different values to update. The substitutions happen at install time (sed over the hook files), not at runtime.

Optional: PostHog product analytics integration

If your team uses PostHog and you have the PostHog MCP connected, AXEL can install the /posthog-weekly skill — an analytical review of your product analytics workspace that finds anomalies, regressions, and improvement opportunities (not a metric dashboard, an actual analyst).

bash bootstrap.sh \
  --user-name "Your Name" \
  --enable-posthog \
  --posthog-context "Acme ATS — recruiting platform with AI sourcing"

What --enable-posthog installs:

• /posthog-weekly skill — pulls dashboards, insights, events, errors, and cohorts from PostHog; identifies dead events, regressions, error backlog, instrumentation gaps, and suggested cohorts; persists a 14-day cached snapshot for other commands to read.
• scripts/posthog-snapshot-loader.sh — bash helper that reads the cached snapshot and prints a markdown summary. Sourceable from any other command (e.g. /sprint-status, /eod-review, /daily) so they include the latest PostHog findings without re-querying.

What --posthog-context does: it gets substituted into the skill's prompt so the analytical lens knows what kind of product it's looking at. A good context is one sentence: name + product type + key features. Example: "Acme Support Desk — B2B ticketing product with search, analytics, and workflow automation". Defaults to a generic placeholder if omitted.

The skill is gated: without --enable-posthog, neither the skill nor the helper script are installed. So teams that don't use PostHog don't get extra files in their ~/.claude/.

# Preview what it does without changing anything:
bash bootstrap.sh --dry-run

Safe to run multiple times. The bootstrap is fully additive — it only adds what's missing, proposes upgrades for existing files, and never overwrites your configuration, memory, or CLAUDE.md.

Optional: iTerm2 session theming (macOS)

A separate, opt-in add-on under extras/iterm-theming/ gives each iTerm2 session a distinct, stable tab color plus a directory and git branch badge, so parallel sessions are easy to tell apart at a glance. It is not run by bootstrap.sh: it is macOS + iTerm2 only, and it is the one component that writes outside ~/.claude (to ~/.config/iterm, ~/.zshrc, and iTerm2 DynamicProfiles). Install it explicitly:

bash extras/iterm-theming/install.sh            # install (idempotent, backs up ~/.zshrc)
bash extras/iterm-theming/install.sh --dry-run  # preview, change nothing

See extras/iterm-theming/README.md for what it does, the commands it adds, and how to revert.

Prerequisites

| Tool | Why | Install | |------|-----|---------| | Claude Code CLI | The tool being configured | docs.anthropic.com | | Node.js >= 18 | Hook scripts (session management, context monitor) | brew install node | | jq | JSON processing in hooks and settings merge | brew install jq | | python3 | Some hook scripts | Ships with macOS |

What's Included

Hooks (18)

The hook system runs automatically during Claude Code lifecycle events:

| Event | Hook | What it does | |-------|------|-------------| | SessionStart | session-restore.sh | Restores context from previous sessions — you pick up where you left off | | UserPromptSubmit | session-auto-title.sh | Auto-names the session from your first prompt — strips greetings, fillers, and assistant-name salutations. Flag-file idempotency so it only fires once per session. | | PreToolUse | --no-verify blocker | Blocks git commit --no-verify — never bypass git hooks | | PreToolUse | validate-commit-format.sh | Validates commit message format: type (Scope): Message. Parses -m flag and heredocs. | | PreToolUse | staging guard | Warns before running anything with RAILS_ENV=staging (= production) | | PostToolUse | proactive-resolver.sh | Auto-starts Docker, PostgreSQL, Redis when they're down. Detects missing deps and suggests install commands | | PostToolUse | post-edit-lint.sh | Auto-runs rubocop/eslint/ruff after file edits (Ruby, TS/JS, Python) | | PostToolUse | gsd-context-monitor.js | Warns the agent when context window is running low (15% warning, 8% critical) with debounce and severity escalation | | PostToolUse | session-log-action.sh | Logs tool actions for session persistence | | PostToolUse | session-checkpoint.sh | Every ~40 tool calls, summarizes progress using Claude Sonnet | | PostToolUse | post-commit-verify.sh | After git commits, suggests launching the excelsior-verifier agent | | PostToolUse | post-commit-memory-trigger.sh | After a git commit, triggers the memory extractor with a 5-minute rate limit to batch consecutive commits | | PostToolUse | linear-lifecycle-sync.sh | Auto-moves Linear cards based on git actions: commit → In Progress, gh pr create → In Review, gh pr merge → Done. Requires Linear MCP. Configurable ticket pattern and repo filter. | | PreCompact | precompact-save-context.sh | Saves rich context snapshot before compaction (git state, pending work, decisions) | | Stop | session-summarize.sh | Compiles a structured session summary using Claude Sonnet | | Stop | memory-extractor.sh | Extracts key learnings and decisions to persistent memory using Claude Sonnet | | Stop | session-cost-log.sh | Logs session cost, tokens, and 5h rate limit consumption to ~/.claude/session-costs.log | | Stop | desktop-notify.sh | macOS notification when Claude finishes (only when terminal is not focused) | | SessionStart (opt-in) | priority-map-staleness.sh | Warns if ~/.claude/memory/priority-map.md hasn't been touched in ≥14 days. Enable by wiring into settings.json SessionStart. | | Cron / weekly (opt-in) | weekly-priority-map-review.sh | Weekly run (e.g., Monday 9am via LaunchAgent) that correlates git activity from the last 7 days against the current priority map and writes an update proposal. Requires PRIORITY_MAP_REPOS env var with space-separated absolute repo paths. |

Note: the two priority-map-* hooks are opt-in — they are not cabled into settings.json by default because they assume ~/.claude/memory/priority-map.md exists. Create that file first, then wire the hooks (SessionStart for staleness, LaunchAgent/cron for the weekly review).

Commands (12 custom)

Slash commands you can use in Claude Code:

| Command | Description | |---------|-------------| | /daily | Daily briefing — pulls Linear issues, calendar events, and blockers (Phase 2: system sync) | | /eod-review | End-of-day review — non-technical tone, audience-aware drafts for Slack/Linear | | /sprint-status | Sprint status report — dual-audience (technical + plain-language), Linear+Notion+Slack aware | | /style | Switch response style: debug, teach, architect, ship (interactive picker) | | /create-pr | Create a PR with auto-generated summary | | /deslop | Remove AI-generated slop from code | | /draft-message | Help structure important Slack/email messages | | /generate-prp | Generate a Product Requirements Prompt from an INITIAL.md | | /execute-prp | Execute an existing PRP step by step | | /multi-repo-feature | Plan and coordinate features spanning multiple repos | | /roadmap | Generate feature and improvement suggestions | | /visualize | Visualize code architecture |

GSD's own commands (now /gsd-* skills) are provided by the get-shit-done installer, not AXEL — see the note at the top of this README.

Agents (23)

Specialized subagents that Claude Code can spawn for focused tasks:

| Category | Agents | |----------|--------| | Verification | excelsior-verifier, production-validator | | Code Quality | bughunter, security-check, cleanup, perf | | Development | feature, debug, tdd-mainder, test-gen, api-design | | Review | review, compare-branch, changelog | | Operations | deploy-check, db-check, incident | | Multi-repo | cross-repo, linear-task | | Communication | draft-message, sprint-summary | | Onboarding | onboard | | GSD System | Installed separately by the get-shit-done package (planner, executor, verifier, researcher, etc.) — not vendored by AXEL |

Usage Monitor

AXEL installs a lightweight Node.js server that runs in the background (via launchd on macOS) and serves a real-time usage dashboard.

Live web dashboard — auto-starts at login, always available at:

http://localhost:9119

Features:

• Summary cards: total cost, today's cost, tokens, 5h rate limit % consumed
• Active sessions panel with live progress bars (context %, 5h %, cost, per-session delta)
• 4 charts: cost/day, 5h% per session, tokens (in+out stacked), sessions by project
• Full session history table with filtering and sorting
• Auto-refreshes every 30 seconds, no page reload needed

Status bar shows live data on every Claude Code interaction:

acme-api | (main) | Sonnet 4.6 | ctx:69% | $1.26 | 5h:22% (+3.2%)

Terminal live view — runs in a terminal pane, updates every 10s:

watch -n 10 -c ~/.claude/tools/session-live.sh

CLI log viewer:

~/.claude/tools/session-costs-view.sh           # last 30 sessions
~/.claude/tools/session-costs-view.sh today     # today only
~/.claude/tools/session-costs-view.sh week      # last 7 days
~/.claude/tools/session-costs-view.sh summary   # totals by day

How the 5h rate limit tracking works:

• The 5h-acum column shows the cumulative % of the 5-hour window used at session close
• The 5h-sesion column shows how much of the limit this specific session consumed (end% - start%)
• The status bar shows both: 5h:22% (+3.2%) = 22% total, this session used 3.2%

Skills (2 + 1 optional)

Multi-file skills with data and scripts:

• memory-review — Review, optimize, and deduplicate the persistent memory system
• ui-ux-pro-max — UI/UX design intelligence with 67 styles, 96 palettes, 57 font pairings, 25 chart types, 13 frontend stacks
• posthog-weekly (optional, requires --enable-posthog at install) — Weekly analytical review of your PostHog workspace. Finds dead events, regressions, instrumentation gaps, error triage debt; suggests cohorts to create; persists a 14-day cached snapshot that other commands can read for daily/sprint reports.

Plugins (10)

Official Claude Code marketplace plugins:

| Plugin | Purpose | |--------|---------| | frontend-design | Anti-slop UI guidelines, auto-activates on frontend tasks | | context7 | Live documentation fetching for any library/framework | | ruby-lsp | Ruby language server integration | | typescript-lsp | TypeScript language server integration | | pyright-lsp | Python type checking integration | | code-simplifier | Simplify and refine code for clarity | | hookify | Create hooks from conversation analysis | | claude-md-management | Audit and improve CLAUDE.md files | | commit-commands | Git commit, push, and PR workflows | | pr-review-toolkit | Comprehensive PR review with specialized agents |

How the Bootstrap Works

For new files: Install

Files that don't exist on your system are copied directly.

For existing files: Propose Upgrade

When a file already exists but the AXEL version is different (potentially better), the bootstrap:

1. Saves the AXEL version to ~/.claude/axel-upgrades/<category>/
2. Generates a MANIFEST.md listing all files with available upgrades
3. Creates a REVIEW.md prompt that your Claude Code agent can follow

To review upgrades, run:

npx axel-setup review-upgrades --target claude --home ~

For portable runtime exports, use the matching target:

npx axel-setup review-upgrades --target codex --codex-home ~/.codex
npx axel-setup review-upgrades --target generic --output ./axel-runtime

Your agent can then compare each file side-by-side, explain what's better in each version, and let you decide: keep current, use AXEL version, or merge the best of both. Nothing changes without your explicit approval.

For installed files: Diff and uninstall

The CLI can audit and remove AXEL-managed files for each runtime target:

npx axel-setup diff --target claude --home ~
npx axel-setup diff --target codex --codex-home ~/.codex
npx axel-setup diff --target generic --output ./axel-runtime

Uninstall is dry-run by default:

npx axel-setup uninstall --target generic --output ./axel-runtime

To remove files, pass --apply:

npx axel-setup uninstall --target generic --output ./axel-runtime --apply

Safety rule: uninstall only removes files that still exactly match the AXEL package. Modified files are kept for manual review. Merge-managed files like settings.json are never removed automatically.

For settings.json: Deep Merge

The bootstrap uses a jq filter to deep-merge settings:

• Scalar values (language, theme, etc.): your existing value always wins
• Hook arrays: AXEL hooks are added alongside yours (deduplicated by command string)
• Plugin map: new plugins are added; if you disabled a plugin, it stays disabled
• Permission arrays: union of both lists
• Environment variables: your existing vars are kept, missing ones are added

For memory: Never Touch

Your memory files are never read, modified, or deleted. The bootstrap only ensures the directory structure exists (~/.claude/memory/, ~/.claude/memory/decisions/).

Memory System

AXEL includes an automatic persistent memory system:

• memory-extractor.sh (Stop hook): At session end, uses Claude Sonnet to analyze the conversation and extract key learnings, decisions, and preferences to ~/.claude/memory/ files
• memory-dedup.sh: Hash-based duplicate detection + orphan cleanup + dead link removal
• session-summarize.sh (Stop hook): Compiles a structured session summary for the next session's context
• session-restore.sh (SessionStart hook): Loads previous session summaries so you pick up where you left off

Memory types: | Type | Purpose | Example | |------|---------|---------| | user | Your role, preferences, expertise | "Senior backend dev, prefers terse responses" | | feedback | How to work with you (dos and don'ts) | "Never mock the database in integration tests" | | project | Technical decisions, team context | "Auth rewrite driven by compliance requirements" | | reference | Where to find things in external systems | "Pipeline bugs tracked in Linear project INGEST" |

Customization

Adding your own hooks

Edit ~/.claude/settings.json and add entries to the relevant event:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "your-custom-hook.sh" }]
      }
    ]
  }
}

Removing components

• Hooks: Delete from ~/.claude/hooks/ and remove the corresponding entry in settings.json
• Commands: Delete from ~/.claude/commands/
• Agents: Delete from ~/.claude/agents/
• Plugins: Set to false in settings.json → enabledPlugins

Language

The default language in the generated CLAUDE.md personal template is Spanish. This applies only to the template file written during install — the CLI itself, the documentation, and all hook/agent code are in English. Change "language" in settings.json to your preferred language for hook output (session summaries, memory extraction, etc.).

Team CLAUDE.md

The template at ~/CLAUDE.md (created only if you don't have one) includes:

• Commit format conventions
• Environment mapping (test/development/staging)
• Excelsior principle configuration
• Multi-repo workflow guidelines

Customize it with your team's specific repos, conventions, and rules.

Security

AXEL writes exclusively to ~/.claude (hooks, agents, commands, skills, settings). All installs are additive: existing files are never silently overwritten, a backup is proposed before any replacement, and settings.json is deep-merged rather than replaced.

Permission profiles: the default --profile core uses acceptEdits mode, which requires explicit confirmation before file edits. The --profile personal and --profile full profiles elevate to bypassPermissions, granting the agent broad autonomy. Only use those profiles when you understand and accept the expanded trust boundary.

Reporting vulnerabilities: please use GitHub private security advisories to report security issues. See SECURITY.md for scope, response commitment, and contact details.

Contributing

Contributions are welcome when they improve AXEL as reusable developer tooling. Start with CONTRIBUTING.md, open a focused issue when the scope is unclear, and keep private company context out of public examples.

What's NOT Touched

These are personal to each developer and are never modified:

• Memory content — all your existing memories stay intact
• Existing hooks — your custom hooks are preserved; new ones are added alongside
• settings.local.json — your personal permission overrides are untouched
• MCP server connections — configured per account (Linear, Slack, GitHub, etc.)
• Disabled plugins — if you've disabled a plugin, the merge respects that

Requirements

• macOS (hooks use macOS-specific features like osascript for notifications)
• Claude Code CLI with an active subscription
• The session-summarize.sh and memory-extractor.sh hooks use claude -p --model sonnet for quality extraction — this consumes API tokens at session end

Troubleshooting

Usage dashboard not responding on http://localhost:9119

On a fresh bootstrap.sh run the launchd agent is installed and loaded automatically. If the dashboard stops responding — usually after a reboot on a machine where the plist was never registered with launchd, or after a manual install that left the plist outside ~/Library/LaunchAgents/ — run these checks:

# 1. Is anything listening on the port?
lsof -iTCP:9119 -sTCP:LISTEN

# 2. Is the launchd agent loaded?
launchctl list | grep claude-monitor

# 3. Is the plist in the right place?
ls -l ~/Library/LaunchAgents/com.*.claude-monitor.plist

If the plist is missing from ~/Library/LaunchAgents/, reinstall it from the template and load it:

USERNAME=$(whoami)
NODE_BIN=$(which node)
PLIST_DEST="$HOME/Library/LaunchAgents/com.${USERNAME}.claude-monitor.plist"

sed -e "s|{{USERNAME}}|$USERNAME|g" \
    -e "s|{{HOME}}|$HOME|g" \
    -e "s|{{NODE_PATH}}|$NODE_BIN|g" \
    ~/.claude/axel-upgrades/templates/claude-monitor.plist > "$PLIST_DEST" 2>/dev/null || \
  sed -e "s|{{USERNAME}}|$USERNAME|g" -e "s|{{HOME}}|$HOME|g" -e "s|{{NODE_PATH}}|$NODE_BIN|g" \
      "$(git -C ~/axel-onboarding rev-parse --show-toplevel 2>/dev/null)/templates/claude-monitor.plist" > "$PLIST_DEST"

launchctl load -w "$PLIST_DEST"
curl -sS -o /dev/null -w "HTTP: %{http_code}\n" http://localhost:9119

Expected output: HTTP: 200. Logs live at ~/.claude/logs/monitor.log and ~/.claude/logs/monitor-error.log.

If the agent runs but the port stays closed, check the error log — most failures are a wrong NODE_PATH (fix: re-run the sed above after updating NODE_BIN) or a permission issue on ~/.claude/session-costs.log.

Release notes

See CHANGELOG.md for the full history of changes grouped by date and scope.

License

MIT