convez.ai
MCP ServerDevOps & InfraestruturaAvançado
cveralyon

AXEL Setup — Configuração de Engenharia para Claude Code

cveralyon/axel-setup

Configuração avançada com agentes, hooks, skills e persistência para Claude Code

Ver no GitHub
BomPluginScore · de 0 a 100

Pacote de configuração production-grade que transforma Claude Code em parceiro de engenharia proativo. Inclui persistência de sessão, memória automática, resolução proativa de erros, agentes especializados, comandos slash e monitor de uso em tempo real.

Instalação

$npx convez-ai cveralyon/axel-setup

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
1
Acompanhando
0
Saúde
71%
Último commit
há 2 semanas
Versão
v0.4.0
Issues abertas
2
Contribuidores
2

Casos de uso

  • Setup reproducível de workflows de engenharia em equipes
  • Automação de verificação e validação de código após mudanças
  • Monitoramento de contexto, tokens e custo em sessões longas
  • Persistência de memória e aprendizados entre sessões

Veredito

Solução madura e opinionada para equipes que adotam Claude Code em workflows de engenharia. Excelente para automação de verificações, persistência de contexto e governança de agentes — requer investimento inicial mas retorna em repetibilidade e auditoria.

README

A tradução para o português deste README ainda está na fila.

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 npm registry install is the primary path:

npx axel-setup --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.

For a macOS one-line installer, use the 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/main/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 /Users/cveralyon/axel-onboarding
npm whoami
npm run check
npm run publish:dry-run
npm publish --access public

From another directory, pass the package path explicitly:

npm publish /Users/cveralyon/axel-onboarding --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 axel-setup@0.2.0 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.

Prerequisites

ToolWhyInstall
Claude Code CLIThe tool being configureddocs.anthropic.com
Node.js >= 18Hook scripts (session management, context monitor)brew install node
jqJSON processing in hooks and settings mergebrew install jq
python3Some hook scriptsShips with macOS

What's Included

Hooks (18)

The hook system runs automatically during Claude Code lifecycle events:

EventHookWhat it does
SessionStartsession-restore.shRestores context from previous sessions — you pick up where you left off
UserPromptSubmitsession-auto-title.shAuto-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 blockerBlocks git commit --no-verify — never bypass git hooks
PreToolUsevalidate-commit-format.shValidates commit message format: type (Scope): Message. Parses -m flag and heredocs.
PreToolUsestaging guardWarns before running anything with RAILS_ENV=staging (= production)
PostToolUseproactive-resolver.shAuto-starts Docker, PostgreSQL, Redis when they're down. Detects missing deps and suggests install commands
PostToolUsepost-edit-lint.shAuto-runs rubocop/eslint/ruff after file edits (Ruby, TS/JS, Python)
PostToolUsegsd-context-monitor.jsWarns the agent when context window is running low (15% warning, 8% critical) with debounce and severity escalation
PostToolUsesession-log-action.shLogs tool actions for session persistence
PostToolUsesession-checkpoint.shEvery ~40 tool calls, summarizes progress using Claude Sonnet
PostToolUsepost-commit-verify.shAfter git commits, suggests launching the excelsior-verifier agent
PostToolUsepost-commit-memory-trigger.shAfter a git commit, triggers the memory extractor with a 5-minute rate limit to batch consecutive commits
PostToolUselinear-lifecycle-sync.shAuto-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.
PreCompactprecompact-save-context.shSaves rich context snapshot before compaction (git state, pending work, decisions)
Stopsession-summarize.shCompiles a structured session summary using Claude Sonnet
Stopmemory-extractor.shExtracts key learnings and decisions to persistent memory using Claude Sonnet
Stopsession-cost-log.shLogs session cost, tokens, and 5h rate limit consumption to ~/.claude/session-costs.log
Stopdesktop-notify.shmacOS notification when Claude finishes (only when terminal is not focused)
SessionStart (opt-in)priority-map-staleness.shWarns 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.shWeekly 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:

CommandDescription
/dailyDaily briefing — pulls Linear issues, calendar events, and blockers (Phase 2: system sync)
/eod-reviewEnd-of-day review — non-technical tone, audience-aware drafts for Slack/Linear
/sprint-statusSprint status report — dual-audience (technical + plain-language), Linear+Notion+Slack aware
/styleSwitch response style: debug, teach, architect, ship (interactive picker)
/create-prCreate a PR with auto-generated summary
/deslopRemove AI-generated slop from code
/draft-messageHelp structure important Slack/email messages
/generate-prpGenerate a Product Requirements Prompt from an INITIAL.md
/execute-prpExecute an existing PRP step by step
/multi-repo-featurePlan and coordinate features spanning multiple repos
/roadmapGenerate feature and improvement suggestions
/visualizeVisualize 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:

CategoryAgents
Verificationexcelsior-verifier, production-validator
Code Qualitybughunter, security-check, cleanup, perf
Developmentfeature, debug, tdd-mainder, test-gen, api-design
Reviewreview, compare-branch, changelog
Operationsdeploy-check, db-check, incident
Multi-repocross-repo, linear-task
Communicationdraft-message, sprint-summary
Onboardingonboard
GSD SystemInstalled 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:

PluginPurpose
frontend-designAnti-slop UI guidelines, auto-activates on frontend tasks
context7Live documentation fetching for any library/framework
ruby-lspRuby language server integration
typescript-lspTypeScript language server integration
pyright-lspPython type checking integration
code-simplifierSimplify and refine code for clarity
hookifyCreate hooks from conversation analysis
claude-md-managementAudit and improve CLAUDE.md files
commit-commandsGit commit, push, and PR workflows
pr-review-toolkitComprehensive 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:

TypePurposeExample
userYour role, preferences, expertise"Senior backend dev, prefers terse responses"
feedbackHow to work with you (dos and don'ts)"Never mock the database in integration tests"
projectTechnical decisions, team context"Auth rewrite driven by compliance requirements"
referenceWhere 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

Default is Spanish. Change "language" in settings.json to your preferred language.

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.

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

Ver o original no GitHub

Bom para

Relacionados