convez.ai
MCP ServerDevOps & InfraestruturaAvançado
zalogarcia

Zalo Claude Code Setup

zalogarcia/zalo-claude-code-setup

Ambiente produção AI em um comando: 7 agentes, 8 MCP servers, automação full

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que transforma Claude Code em um ambiente de engenharia de IA pronto para produção com um único comando. Inclui 7 agentes pré-configurados, 8 servidores MCP, 22 comandos, 4 skills, hooks de auto-formatação e um dashboard de autoloop para automação completa de workflows.

Instalação

$npx convez-ai zalogarcia/zalo-claude-code-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
3
Forks
1
Acompanhando
0
Saúde
28%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Configurar ambiente de desenvolvimento AI engineer pronto para produção
  • Automatizar workflows de planejamento, execução e QA em projetos
  • Integrar múltiplos agentes especializados (planner, executor, tester, qa) em um sistema
  • Implementar hooks de auto-formatação e verificação contínua em projetos

Veredito

Setup altamente opinado e completo para quem trabalha com Claude Code em escala. Requer conhecimento sólido de shell, Node.js, Python e git — não é para iniciantes. Entrega real: 7 agentes funcionais, automação comprovada e visualização interativa da arquitetura.

README

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

Zalo's Claude Code Setup

One command to turn Claude Code into a production-grade AI engineering environment.

Custom agents, skills, commands, MCP servers, auto-formatting hooks, and workflow automation — all preconfigured and ready to go.


Interactive Architecture

See how the pieces fit together: 7 agents, 16 shared rules, 6 commands, 8 skills, hooks, MCP servers — plus animated request flows (/autopilot, /bug, /qa-loop, /brainstorm, /plan).

→ Open the interactive visualization

Click any node to inspect its contract (completion markers, @-includes, dispatches). Pick a flow from the dropdown to watch a request travel through the system. Works on mobile with a vertical storyboard mode.


Recommended Workflow

This is how I use Claude Code to get the best results on any task:

Plan + Research  -->  Optimize Plan  -->  Execute in Phases  -->  Verify + Test  -->  Repeat
  1. Plan + Research — Before touching code, have Claude research the problem and produce a written plan (safe-planner agent or /plan). Understand the blast radius.
  2. Optimize the plan — Review the plan, ask questions, refine. Get alignment before execution.
  3. Execute in phases — Break the work into small, shippable phases. Implement one phase at a time.
  4. Verify + test after each phase — Run builds, tests, and visual checks (live-test agent) after every phase. Never stack unverified changes.
  5. Continue implementing — Move to the next phase only after the current one passes.
  6. Run QA multiple times — Use the qa-agent repeatedly until all bugs are fixed. Don't ship until it passes clean.

This loop ensures nothing slips through. Plan first, execute small, verify always.


Quick Install

Prerequisites

Make sure these are installed first:

ToolInstall CommandPurpose
Node.js + npmnodejs.org or brew install nodeRequired for MCP servers and npx
Python 3brew install python3Required for hook scripts (gitleaks guard, stop-hook)
jqbrew install jqRequired for hook JSON parsing
Prettiernpm install -g prettierAuto-formats TS/JS/CSS/JSON/MD/HTML on every edit
Ruffpip install ruffAuto-formats and lints Python on every edit
uvpip install uvOptional — used by some skills' Python scripts
Gitbrew install gitRequired for cloning this repo

Run the Installer

git clone https://github.com/zalogarcia/zalo-claude-code-setup.git
cd zalo-claude-code-setup
./install.sh

The installer will:

  1. Back up all your existing Claude Code configs to ~/.claude/backups/
  2. Copy agents to ~/.claude/agents/
  3. Copy commands to ~/.claude/commands/
  4. Copy skills to ~/.claude/skills/ and workflows to ~/.claude/workflows/
  5. Install global CLAUDE.md to ~/.claude/
  6. Merge hooks into ~/.claude/settings.json (preserves your existing hooks)
  7. Merge MCP servers into ~/.claude.json (skips servers you already have)
  8. Prompt for API keys — enters them directly into MCP server configs where they're needed
  9. Create ~/.claude/settings.local.json with env var placeholders for Bash tools (if not exists)

Safe to run multiple times — it deduplicates and never overwrites your existing configs.

Important: MCP servers need actual API key values directly in ~/.claude.json. The ${VAR} syntax does NOT work for MCP env vars — it only works for Bash tool sessions. The installer handles this for you by prompting during setup.


API Keys: How to Get Them

The installer will prompt you for these during setup. Here's how to get each one:

GitHub Personal Access Token (required for GitHub MCP)

  1. Go to github.com/settings/tokens
  2. Click "Generate new token" (Fine-grained token recommended)
  3. Give it a name like claude-code
  4. Set expiration (90 days recommended)
  5. Under Repository access, select the repos you want Claude to access
  6. Under Permissions, grant: Contents (read/write), Pull requests (read/write), Issues (read/write)
  7. Click Generate token and copy it

Supabase Access Token (required for Supabase MCP)

  1. Go to supabase.com/dashboard/account/tokens
  2. Click "Generate new token"
  3. Give it a name like claude-code
  4. Copy the token (starts with sbp_)

Cloudflare API Token (optional — for cf-crawl website scraping skill)

  1. Go to dash.cloudflare.com/profile/api-tokens
  2. Click "Create Token"
  3. Use the "Edit Cloudflare Workers" template (or create custom with Browser Rendering permissions)
  4. Copy the token
  5. Find your Account ID in the Cloudflare dashboard sidebar

Where Keys End Up

KeyLocationUsed By
GitHub PAT~/.claude.json > mcpServers.github.envGitHub MCP server
Supabase token~/.claude.json > mcpServers.supabase.envSupabase MCP server
Cloudflare token~/.claude/settings.local.json > envcf-crawl skill (via Bash)

~/.claude.json is local-only and never committed to git. settings.local.json is chmod 600 (owner-only).

Restart Claude Code

Close and reopen Claude Code to pick up all changes.


What's Included

Custom Agents (7)

AgentWhat It Does
qa-agentAudits code for real, reproducible bugs. Categorizes by severity (critical/high/medium/low). Run it after every feature.
safe-plannerReads all related code, maps dependencies and risks, produces a rollback-ready plan. Use before any non-trivial change.
live-testOpens the app in a real browser via Playwright. Screenshots happy path, edge cases, and 3 responsive breakpoints.
frontend-specialistBuilds production-quality UI with Aceternity UI and shadcn/ui MCP access. Reads Apple HIG principles before coding.
bug-fixTraces the full user flow to find root cause. Reads all related code and crafts a comprehensive fix plan before changes.
outcomes-graderGrades plans and artifacts against the engineering-principles rubric. Returns PASS/FAIL with quoted evidence per outcome.
brainstormDeep-thinking agent that challenges assumptions, eliminates complexity, and stress-tests plans using first principles, Elon Musk's 5-step philosophy, inversion, and second-order thinking.

Commands (6)

Slash commands for workflow automation. Invoke with /<command-name>.

CommandWhat It Does
autopilotAutonomous multi-phase orchestrator: plan → implement → QA → commit
autopilot-mergeConsolidates completed autopilot worktrees back into the main branch
bugBug-fix workflow: trace, diagnose, fix, validate
qa-loopIterative audit-and-fix loop — finds and fixes bugs until the codebase is clean
planPlan something with brainstorm + principles verification
brainstormDeep-analyze a problem, plan, or decision with first principles, inversion, and structured elimination

Skills (8)

SkillWhat It Does
typecheck-and-buildStandardizes tsc --noEmit + production build with smart failure-region extraction and consistent exit codes.
commit-with-heredocEncodes correct $(cat <<'EOF' … EOF) quoting for multi-line conventional commits with Co-Authored-By trailer.
dev-server-restartShell script that kills any stale dev server on a port, restarts via nohup, polls for readiness, smoke-tests a route.
autopilot-collectUsed by /autopilot worktrees to bundle their diff + decisions log into a single review-ready artifact.
frontend-designAnti-slop aesthetic guidelines. Bold design direction, distinctive typography, no generic AI look. (Opt-in via frontend chain.)
create-skillAuthor a new Claude Code skill following the established pattern — decision tree, form factor, template, registration.
cf-crawlScrape websites via Cloudflare Browser Rendering API. Single page (sync) or multi-page crawl (async).
live-test-campaignMaster live-test campaign against a deployed app: design-review the code first, enumerate edge cases by lifecycle stage, split live-vs-lab, then run a cheapest-first phase ladder with positive-evidence discipline and state neutralization.

Workflows (2)

Deterministic multi-agent scripts at ~/.claude/workflows/, run via Claude Code's Workflow tool. Commands delegate to them and fall back to inline agent dispatch when workflows are unavailable.

WorkflowWhat It Does
qa-auditRead-only audit backing /qa-loop: 6 parallel finder agents (correctness, wiring, error-handling, security, stubs, types-edges) + 2-skeptic adversarial verification — returns only confirmed bugs.
plan-verifyPlan Verification Loop backing /plan: brainstorm critique + principles grading in parallel, then at most one safe-planner revision pass.

Shared Rules (16)

Authoritative reference docs at ~/.claude/rules/. Commands and agents @-include them; the main thread reads them when the situation applies. Built from the best of gsd-build/get-shit-done + obra/superpowers.

RuleWhat It Governs
agent-contracts.mdH2 completion markers + DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED status protocol
gates.md4 workflow gate types (pre-flight / revision / escalation / abort) + 5-step Verification Gate
checkpoints.mdHuman-in-loop XML schema (checkpoint:human-verify / :decision / :human-action)
verification-patterns.md"Existence ≠ Implementation" — stub-detection greps + wiring checks
anti-patterns.mdUniversal failure modes (placeholders, silent partial completion, drift) + No-Placeholders list
questioning.mdDream-extraction philosophy for requirements gathering
context-budget.mdPEAK / GOOD / DEGRADING / POOR tier behaviors + degradation warning signs
persuasion-principles.mdCialdini-derived patterns for writing rules that actually get followed
when-to-parallelize.md4-criteria decision rule for parallel agent dispatch
problem-solving.mdWhen-stuck dispatch table (inversion / simplification / meta-pattern) + 3+ Fixes Rule
git-safety.mdStaging discipline, pre-op checks, destructive-op approval
api-retry.mdExponential-backoff + circuit-breaker protocol for transient Anthropic API errors during agent dispatch
database-safety.mdAdditive-only migrations + expand-contract pattern for breaking schema changes
engineering-principles.mdRubric outcomes-grader uses to score plans (architectural coherence, scope integrity, failure resilience, ...)
plan-verification.mdTwo-gate verification loop (brainstorm + outcomes-grader) applied after every safe-planner plan
testing-safety.mdAdmin-account-only rule for live-system tests; no fake users against production

Meta-Rule (Session-Start Re-injection)

~/.claude/META_RULE.md is automatically re-injected at every startup, /clear, and /compact via the session-start.sh hook. It names the available primitives (subagents, slash commands, skills, shared rules) and the discipline for routing work — so the orchestrator never forgets the system's shape. Edit freely; the hook reads it fresh each time.

MCP Servers (4)

ServerWhat It Does
context7Documentation lookup for any library or framework (React, Next.js, Supabase, etc.). Always up-to-date.
playwrightBrowser automation — navigate, click, fill forms, screenshot. Powers the live-test agent.
githubFull GitHub API — create PRs, manage issues, search code, push files. Requires GITHUB_PAT.
supabaseManage Supabase projects — run SQL, deploy edge functions, manage migrations. Requires SUPABASE_ACCESS_TOKEN.

Optional add-ons for large codebases

This setup deliberately ships a lean MCP server list. If you work in large codebases (5,000+ files, deep call chains, hard-to-grep architecture), two community MCPs add real leverage on top:

  • repo-graphrag — code-aware knowledge graph using Tree-sitter + LightRAG. Lets Claude answer architecture questions ("where does the auth token flow?") and produce structurally-aware plans without grepping the whole tree. A global git post-commit hook keeps the graph fresh.
  • mcp-server-qdrant — local semantic memory. Stores patterns, decisions, and solutions across conversations so Claude doesn't relearn your house style every session.

Both run locally (no external API). Add them to ~/.claude.json under mcpServers after install. Skip if your codebase is small enough that grep is faster than indexing.

xbar Menu Bar Plugins

macOS menu bar integration via xbar:

PluginWhat It Does
001-shortcuts.1d.shCustom keyboard shortcuts menu for common Claude Code operations
002-clipboard-snippets.1d.shClipboard snippet manager for reusable prompts and code fragments

Plus 21 helper scripts in scripts/ for launching Claude Code sessions in specific project contexts, clipboard-based prompt workflows (plan-first, bug-fix, verify), and window layout capture/restore.

Memory Files

Curated design principles and learned patterns that persist across all conversations:

FileWhat It Contains
apple_hig_design_principles.md87 standards across 26 sections from Apple HIG — the frontend agent reads this before writing any UI code
apple_hig_menu_bar_principles.mdMenu bar anatomy, ordering, labeling, shortcuts from Apple HIG
feedback_finetuning_style.mdLearned response style preferences for training data generation

Auto-Formatting Hooks

Every time Claude edits a file, it's automatically formatted before you see it:

File TypesFormatterInstall
.ts .tsx .js .jsx .css .json .md .htmlPrettiernpm install -g prettier
.pyRuff (format + lint fix)pip install ruff

Global CLAUDE.md

Behavioral rules that make Claude Code significantly more effective:

  • Self-learning — When you correct Claude, it saves the lesson to prevent repeating mistakes
  • Project init — Auto-scaffolds .claude/CLAUDE.md and .claude/rules/ for new projects
  • Frontend chain (opt-in) — For UI work, optionally invoke the chain: design search → aesthetic guidelines → specialist agent (with Aceternity UI + shadcn/ui MCP access + Apple HIG principles) → visual verification
  • Verification-first — Claude proves changes work (build, test, screenshot) instead of saying "this should work"
  • Context survival — Plans are written to files so they survive compaction and session transfers
  • Subagent orchestration — Complex work is delegated to specialized agents, keeping the main context clean
  • Compact + plan files — long workflows write to docs/PLAN.md so they survive /compact and context limits

Frontend Workflow (Opt-In)

When you ask Claude to build non-trivial UI (a new page, a component-library piece, a visual redesign), consider invoking this chain. It's opt-in — skip for trivial copy/style tweaks:

  1. frontend-design skill — Applies anti-slop aesthetic principles (no generic Inter + purple gradient)
  2. frontend-specialist agent — Builds production-quality code with Aceternity UI + shadcn/ui component libraries, applies Apple HIG-quality design principles throughout
  3. live-test agent — Opens a browser and screenshots the result for visual verification

Default Tech Stack

When you don't specify, Claude defaults to:

LayerDefault
FrontendReact + TypeScript + Tailwind CSS
BackendSupabase (Edge Functions, Auth, RLS, Storage)
PaymentsStripe
DeploymentVercel or Supabase hosting
Package managernpm
TestingVitest for unit, Playwright for e2e

Dependencies Summary

Everything you need to install for the full setup to work:

# System tools (macOS)
brew install node python3 jq git

# Global npm packages
npm install -g prettier

# Python packages
pip install ruff uv
DependencyRequired ByRequired?
Node.js + npmMCP servers (github, supabase, playwright)Yes
Python 3Hook scripts (gitleaks guard, stop-hook)Yes
jqHook JSON parsingYes
GitInstaller (clones this repo)Yes
PrettierAuto-format hook (TS/JS/CSS/JSON/MD/HTML)Recommended
RuffAuto-format hook (Python)Recommended
uv/uvxOptional — Python tooling for some skillsOptional

If a recommended tool is missing, the relevant hook or MCP will silently skip — nothing breaks.


File Structure

.
├── README.md
├── install.sh                        # One-command installer (backs up first)
├── uninstall.sh                      # Restore from backup
├── CLAUDE.md                         # Global behavioral instructions
├── META_RULE.md                      # Re-injected on every session-start / /clear / /compact
├── agents/
│   ├── qa-agent.md                   # Bug auditor
│   ├── safe-planner.md               # Risk-aware planner
│   ├── live-test.md                  # Browser verification
│   ├── frontend-specialist.md        # UI builder (Aceternity + shadcn MCPs)
│   ├── bug-fix.md                    # Root cause tracer
│   ├── outcomes-grader.md            # Plan/artifact rubric grader
│   └── brainstorm.md                 # Deep-thinking problem analyzer
├── commands/
│   ├── autopilot.md                  # Autonomous multi-phase orchestrator
│   ├── autopilot-merge.md            # Consolidate autopilot worktrees back into main
│   ├── bug.md                        # Bug trace + diagnose + fix + validate
│   ├── qa-loop.md                    # Iterative audit-and-fix loop
│   ├── plan.md                       # Plan with brainstorm + principles verification
│   └── brainstorm.md                 # Deep-analyze problems and plans
├── skills/
│   ├── typecheck-and-build/
│   │   └── SKILL.md                  # tsc + build with smart failure-region extraction
│   ├── commit-with-heredoc/
│   │   └── SKILL.md                  # Correct heredoc quoting for multi-line commits
│   ├── dev-server-restart/
│   │   ├── SKILL.md                  # Dev-server restart contract
│   │   └── restart.sh                # Kill+nohup+poll+smoke-test executable
│   ├── autopilot-collect/
│   │   ├── SKILL.md                  # Bundle worktree diff + decisions log
│   │   └── collect.sh                # Collection runner
│   ├── frontend-design/
│   │   └── SKILL.md                  # Anti-slop aesthetics
│   ├── create-skill/
│   │   └── SKILL.md                  # Meta-skill: author new skills with the established pattern
│   ├── cf-crawl/
│   │   └── SKILL.md                  # Web scraper
│   └── live-test-campaign/
│       └── SKILL.md                  # Master live-test campaign methodology
├── workflows/
│   ├── qa-audit.js                   # Parallel bug hunt + adversarial verify (backs /qa-loop)
│   └── plan-verify.js                # Two-gate plan verification (backs /plan)
├── hooks/
│   ├── settings.json                 # Hook configuration (formatters, gitleaks, session-start)
│   ├── continue-if-incomplete.py     # Stop hook: nudge Claude if it halts mid-task
│   ├── reset-stop-counter.sh         # UserPromptSubmit hook: reset nudge counter
│   ├── session-start.sh              # SessionStart hook: inject META_RULE.md
│   └── gitleaks-guard.py             # PreToolUse hook: block git commit/push if gitleaks finds secrets
├── mcp/
│   ├── mcp-servers.json              # MCP server configs
│   └── env-template.json             # API key placeholders
├── .archive/                         # Deprecated subprojects (orchestrator, autoloop-dashboard)
└── xbar/
    └── plugins/
        ├── 001-shortcuts.1d.sh       # Keyboard shortcuts menu
        ├── 002-clipboard-snippets.1d.sh  # Clipboard snippets
        └── scripts/                  # 21 helper scripts (launchers, clips, layout)

Uninstall

Restores everything from the backup created during install:

./uninstall.sh

Handles both scenarios:

  • Had existing configs — Restores them from backup
  • Fresh install — Cleanly removes everything that was added

License

MIT

Ver o original no GitHub

Bom para

Relacionados