Skip to content

Instalacao

Jump to bottom
Petrus Silva Costa edited this page Aug 17, 2026 · 1 revision

Installation

English below · Português abaixo

This page teaches you how to install the bigtech plugin into Claude Code, step by step, without assuming prior knowledge. If a term does not make sense, check the Glossary.

Before you start

You need to already have Claude Code installed and working on your computer. Claude Code runs in the terminal (the text command window). The commands that begin with a slash (/) are typed inside Claude Code, not in the regular terminal.

Step 0: prerequisites per operating system

Before installing, the plugin needs one thing on your machine: Python 3, reachable by the name python3.

Why? The plugin uses small helper programs called hooks (they run automatically at moments like the start of a session). These hooks are written in the Python language, and the plugin starts them by calling the command python3. If your computer does not understand that command, the hooks do not run and the plugin stays inert (it installs, but does nothing). "Reachable on the PATH" means: when you type python3 in the terminal, the system finds and runs it. The PATH is the list of folders the system searches for commands.

First, check whether you already have it. In the regular terminal (not inside Claude Code), type:

python3 --version

If it prints something like Python 3.12.3, you are done; skip to Step 1. If it says "command not found" (or similar), follow the part below for your system.

Linux

Python 3 is almost always already installed. In the rare case it is missing, install it with your system's package manager (the program that installs software). Pick the line that matches your distribution:

sudo apt install python3      # Debian, Ubuntu, Mint
sudo dnf install python3      # Fedora, RHEL
sudo pacman -S python         # Arch, Manjaro
sudo zypper install python3   # openSUSE

sudo asks for your password because installing system software needs administrator permission. After it finishes, run python3 --version again to confirm.

macOS

macOS does not always ship a python3. The two common ways to get it:

  • Xcode Command Line Tools (Apple's developer toolkit; no full Xcode needed). In the terminal: 
    xcode-select --install
    A dialog opens; accept and wait for it to finish.
  • Homebrew (a popular package manager for macOS). If you already have brew: 
    brew install python

Then run python3 --version to confirm it is reachable.

Windows (native)

This is the case that needs the most attention. The plugin calls the command python3, and on Windows not every Python install creates that exact name. You have three options; pick one.

  • Option A (recommended): Python from the Microsoft Store. Open the Microsoft Store, search for "Python 3", and install the latest version. The Store version automatically registers both the python3 and python aliases, so the plugin finds it with no extra step. Then, in a new terminal window, confirm: 
    python3 --version
  • Option B: the installer from python.org. This installer gives you python and a launcher called py, but it does not guarantee the name python3. So python3 --version may fail even though Python is installed. To fix it, the plugin ships a tiny helper file at bin/python3.cmd that simply forwards python3 to py -3 (or to python). Copy that file into a folder that is on your PATH; an easy one that already exists is: 
    %LOCALAPPDATA%\Microsoft\WindowsApps
    After copying, open a new terminal and check python3 --version. (If you prefer, you can instead create your own alias; the shim is just the simplest path.)
  • Option C: WSL (Windows Subsystem for Linux). WSL runs a real Linux inside Windows. If you run Claude Code from WSL, follow the Linux instructions above; everything works exactly as on Linux. This is the smoothest option if you are comfortable with WSL.

Whichever option you choose, the goal is the same: python3 --version must print a version. The companion dependencies and the agents' own tools do not need to be installed by hand here; they are handled later (see below).

Official host (GitHub only)

The plugin lives only on GitHub: github.com/petrinhu/bigtech_plugin. There is no official Codeberg, Forgejo, or other forge mirror. Always use the marketplace URL below (github.com/petrinhu/bigtech_plugin). If you find an old link to another host, ignore it and install from GitHub.

Step 1: install through the main path

Open Claude Code and type the two commands below, one at a time, in order:

/plugin marketplace add github.com/petrinhu/bigtech_plugin
/plugin install bigtech@petrinhu

What each one does:

  • The first command registers the marketplace (the plugin store) called petrinhu. It is like adding an app source before downloading an app.
  • The second command installs the bigtech plugin from that store. The bigtech@petrinhu form makes clear which store it comes from; if you only have that one store registered, /plugin install bigtech also works.

Step 2: restart the session

After installing, close and reopen Claude Code (restart the session). This is necessary because the plugin has a hook called bigtech-session-init that only runs when the session starts. It is the one that loads the manuals and prepares the operating mode. Without restarting, the plugin is not fully active.

See what this hook does in Hook: bigtech-session-init.

Step 3: check that it worked

Check three signs. If any of them fails, the plugin was not installed correctly.

  1. The 51 agents show up. List the agents available in Claude Code and look for the leadership ones (such as celso-ceo and caetano-cto) and a few operational ones (such as backend-engineer and technical-writer).
  2. The 4 skills exist. The commands /bigtech, /proj_software, /tab_pendencias, and /visual-design-director should be available.
  3. The hooks run. When starting a new session, the plugin should inject the path of the manuals into the context. Use the /plugin command to confirm that bigtech is active.

Important warning: name conflicts

This is the most delicate point of the installation. Check before installing. Homonymous global agents, skills, or hooks in ~/.claude/ collide with the plugin and can double-run TDD hooks.

If your Claude Code already has global agents, skills, or hooks (defined in your configuration folder ~/.claude/, outside any plugin) with the same names as the ones the plugin brings, installing on top causes duplication and conflict. The most common collision cases:

  • Agents with the same name, for example an existing celso-ceo.
  • Skills with the same name, for example /bigtech or /tab_pendencias.
  • The most serious case: test hooks with the same name would run twice (the global version plus the plugin's), which can block or run the test suite in duplicate.

How to check beforehand

Look for collisions in these three places of your global configuration:

  1. In the ~/.claude/agents/ folder, files with the same names as the plugin's agents.
  2. In the ~/.claude/skills/ (or ~/.claude/commands/) folder, the commands /bigtech, /proj_software, /tab_pendencias.
  3. In the ~/.claude/hooks/ folder, test or governance hooks with the same names (tdd_guard, tdd_runner, bigtech_*).

If there is a conflict, choose a safe way out

Do not install on top. There are two ways out; the first is the recommended one.

Recommended option: isolated environment

Install the plugin in a clean environment, pointing Claude Code to another configuration folder. This is done with an environment variable called CLAUDE_CONFIG_DIR. Before opening Claude Code, in the terminal, you set this variable pointing to a separate folder. That way the plugin does not compete for names with your normal configuration.

The idea in plain words: you create a separate "profile" of Claude Code just to use the plugin, without touching your usual profile. Each profile has its own agents, skills, and hooks, without mixing.

Alternative option: remove the globals with the same name

Carefully remove or rename the global agents, skills, and hooks that collide, before installing the plugin. Treat this as a change that deletes things: confirm item by item before removing, because it cannot be easily undone.

Alternative: install from a local copy

Use this method if you have no internet, if the remote registry fails, or if you want to install from a copy you already downloaded. Clone from GitHub only (same official host as the marketplace).

First, in the regular terminal, clone the repository:

git clone https://github.com/petrinhu/bigtech_plugin

Then, in Claude Code, register the marketplace pointing to the downloaded folder and install:

/plugin marketplace add <path-to-downloaded-folder>
/plugin install bigtech

Replace <path-to-downloaded-folder> with the full path of the folder where you downloaded the repository (the folder that contains the file .claude-plugin/marketplace.json).

Compatibility

  • Platform. Works on Linux, macOS, and Windows (native or WSL). The hooks are pure Python and run cross-platform; the one requirement is that python3 is reachable (see Step 0). Beyond that, no OS-specific setup is needed.
  • Agent tools are handled automatically. When an agent needs an external tool (for a test, a scan, a diagram), it installs the small, no-permission ones on its own and asks you before any install that needs administrator rights, always picking the right command for your OS. You do not pre-install a toolbox; nothing is installed silently.
  • Incompatible with the caveman plugin. caveman shortens and compresses communication, which conflicts with bigtech's mode reinforcement. If you use caveman, disable it before using bigtech. The session-start hook warns when it detects both active at the same time.
  • Suggested dependencies (optional): playwright and superpowers. They are not mandatory, but they enable the full experience. They are installed through Claude Code (with slash commands), the same way on every operating system, not through your system's package manager. The session-start hook suggests installing them when they are missing.
  • For UI/design work: also install Anthropic's frontend-design skill, if it is not already installed. It helps produce distinctive visual design instead of generic templates. In Claude Code, run /plugin marketplace add anthropics/skills and then /plugin install example-skills@anthropic-agent-skills. It is optional (the frontend-engineer agent already embeds these principles), but recommended.

Security

The hooks in this plugin run code on your computer. In particular, the tdd-runner hook runs the test command declared by the project you open. This carries the same trust as running make test or npm test in a repository: the command comes from a file of the project itself.

Before using the plugin in third-party repositories you do not know, check which test command is configured in the project's .claude/tdd-guard.json file. To turn off TDD control during a session, set the environment variable TDD_GUARD=off in the terminal. The repository's SECURITY.md document has the full detail.

Next step: learn the day-to-day Usage. Back to the Home.

Instalação

English above · Português abaixo

Esta página ensina a instalar o plugin bigtech no Claude Code, passo a passo, sem assumir conhecimento prévio. Se um termo não fizer sentido, consulte o Glossário.

Antes de começar

Você precisa ter o Claude Code já instalado e funcionando no seu computador. O Claude Code roda no terminal (a janela de comandos de texto). Os comandos que começam com uma barra (/) são digitados dentro do Claude Code, não no terminal comum.

Passo 0: pré-requisitos por sistema operacional

Antes de instalar, o plugin precisa de uma coisa na sua máquina: o Python 3, alcançável pelo nome python3.

Por quê? O plugin usa pequenos programas auxiliares chamados hooks (eles rodam sozinhos em momentos como o início de uma sessão). Esses hooks são escritos na linguagem Python, e o plugin os inicia chamando o comando python3. Se o seu computador não entende esse comando, os hooks não rodam e o plugin fica inerte (ele instala, mas não faz nada). "Alcançável no PATH" quer dizer: quando você digita python3 no terminal, o sistema encontra e executa. O PATH é a lista de pastas onde o sistema procura os comandos.

Primeiro, confira se você já tem. No terminal comum (não dentro do Claude Code), digite:

python3 --version

Se aparecer algo como Python 3.12.3, está pronto; pule para o Passo 1. Se disser "command not found" (ou parecido), siga a parte abaixo do seu sistema.

Linux

O Python 3 quase sempre já vem instalado. No caso raro de faltar, instale com o gerenciador de pacotes do seu sistema (o programa que instala softwares). Escolha a linha que combina com a sua distribuição:

sudo apt install python3      # Debian, Ubuntu, Mint
sudo dnf install python3      # Fedora, RHEL
sudo pacman -S python         # Arch, Manjaro
sudo zypper install python3   # openSUSE

O sudo pede a sua senha porque instalar software de sistema precisa de permissão de administrador. Quando terminar, rode python3 --version de novo para confirmar.

macOS

O macOS nem sempre traz um python3. As duas formas comuns de obter:

  • Xcode Command Line Tools (o kit de desenvolvedor da Apple; não precisa do Xcode completo). No terminal: 
    xcode-select --install
    Abre uma janela; aceite e espere terminar.
  • Homebrew (um gerenciador de pacotes popular no macOS). Se você já tem o brew: 
    brew install python

Depois rode python3 --version para confirmar que está alcançável.

Windows (nativo)

Este é o caso que mais pede atenção. O plugin chama o comando python3, e no Windows nem toda instalação de Python cria esse nome exato. Você tem três opções; escolha uma.

  • Opção A (recomendada): Python da Microsoft Store. Abra a Microsoft Store, busque por "Python 3" e instale a versão mais recente. A versão da Store registra automaticamente os aliases python3 e python, então o plugin a encontra sem passo extra. Depois, em uma nova janela de terminal, confirme: 
    python3 --version
  • Opção B: o instalador do python.org. Esse instalador te dá o python e um launcher chamado py, mas não garante o nome python3. Por isso python3 --version pode falhar mesmo com o Python instalado. Para resolver, o plugin traz um arquivinho auxiliar em bin/python3.cmd que simplesmente encaminha o python3 para o py -3 (ou para o python). Copie esse arquivo para uma pasta que esteja no seu PATH; uma fácil, que já existe, é: 
    %LOCALAPPDATA%\Microsoft\WindowsApps
    Depois de copiar, abra um terminal novo e verifique python3 --version. (Se preferir, você pode em vez disso criar o seu próprio alias; o shim é só o caminho mais simples.)
  • Opção C: WSL (Subsistema do Windows para Linux). O WSL roda um Linux de verdade dentro do Windows. Se você roda o Claude Code pelo WSL, siga as instruções de Linux acima; tudo funciona exatamente como no Linux. É a opção mais tranquila se você se sente à vontade com o WSL.

Qualquer que seja a opção, o objetivo é o mesmo: python3 --version precisa imprimir uma versão. As dependências companion e as próprias ferramentas dos agents não precisam ser instaladas à mão aqui; elas são tratadas mais adiante (veja abaixo).

Host oficial (somente GitHub)

O plugin vive só no GitHub: github.com/petrinhu/bigtech_plugin. Não há espelho oficial em Codeberg, Forgejo ou outro forge. Use sempre a URL de marketplace abaixo (github.com/petrinhu/bigtech_plugin). Se aparecer link antigo de outro host, ignore e instale a partir do GitHub.

Passo 1: instalar pelo caminho principal

Abra o Claude Code e digite os dois comandos abaixo, um de cada vez, na ordem:

/plugin marketplace add github.com/petrinhu/bigtech_plugin
/plugin install bigtech@petrinhu

O que cada um faz:

  • O primeiro comando registra o marketplace (a loja de plugins) chamado petrinhu. É como adicionar uma fonte de aplicativos antes de baixar um app.
  • O segundo comando instala o plugin bigtech a partir dessa loja. A forma bigtech@petrinhu deixa claro de qual loja vem; se você só tiver essa loja registrada, /plugin install bigtech também funciona.

Passo 2: reiniciar a sessão

Depois de instalar, feche e abra o Claude Code de novo (reinicie a sessão). Isso é necessário porque o plugin tem um hook chamado bigtech-session-init que só roda quando a sessão começa. É ele que carrega os manuais e prepara o modo de operação. Sem reiniciar, o plugin não fica plenamente ativo.

Veja o que esse hook faz em Hook: bigtech-session-init.

Passo 3: conferir se deu certo

Confira três sinais. Se algum falhar, o plugin não foi instalado corretamente.

  1. Os 51 agentes aparecem. Liste os agentes disponíveis no Claude Code e procure os de liderança (como celso-ceo e caetano-cto) e alguns operacionais (como backend-engineer e technical-writer).
  2. As 4 skills existem. Os comandos /bigtech, /proj_software, /tab_pendencias e /visual-design-director devem estar disponíveis.
  3. Os hooks rodam. Ao iniciar uma sessão nova, o plugin deve injetar no contexto o caminho dos manuais. Use o comando /plugin para confirmar que o bigtech está ativo.

Aviso importante: conflito de nomes

Este é o ponto mais delicado da instalação. Verifique antes de instalar. Agents, skills ou hooks globais homônimos em ~/.claude/ colidem com o plugin e podem rodar hooks de TDD em duplicidade.

Se o seu Claude Code já tiver agentes, skills ou hooks globais (definidos na sua pasta de configuração ~/.claude/, fora de qualquer plugin) com os mesmos nomes dos que o plugin traz, instalar por cima causa duplicação e conflito. Os casos mais comuns de colisão:

  • Agentes com nome igual, por exemplo um celso-ceo já existente.
  • Skills com nome igual, por exemplo /bigtech ou /tab_pendencias.
  • O caso mais grave: hooks de teste com o mesmo nome rodariam duas vezes (a versão global mais a do plugin), o que pode bloquear ou rodar a suite de testes em duplicidade.

Como verificar antes

Procure colisões nestes três lugares da sua configuração global:

  1. Na pasta ~/.claude/agents/, arquivos com os mesmos nomes dos agentes do plugin.
  2. Na pasta ~/.claude/skills/ (ou ~/.claude/commands/), os comandos /bigtech, /proj_software, /tab_pendencias.
  3. Na pasta ~/.claude/hooks/, hooks de teste ou governança com nomes iguais (tdd_guard, tdd_runner, bigtech_*).

Se houver conflito, escolha uma saída segura

Não instale por cima. Há duas saídas; a primeira é a recomendada.

Opção recomendada: ambiente isolado

Instale o plugin em um ambiente limpo, apontando o Claude Code para outra pasta de configuração. Isso é feito com uma variável de ambiente chamada CLAUDE_CONFIG_DIR. Antes de abrir o Claude Code, no terminal, você define essa variável apontando para uma pasta separada. Assim o plugin não disputa nomes com a sua configuração normal.

A ideia em palavras simples: você cria um "perfil" separado do Claude Code só para usar o plugin, sem mexer no seu perfil de sempre. Cada perfil tem seus próprios agentes, skills e hooks, sem se misturar.

Opção alternativa: remover os globais com mesmo nome

Com cuidado, remova ou renomeie os agentes, skills e hooks globais que colidem, antes de instalar o plugin. Trate isso como uma mudança que apaga coisas: confirme item por item antes de remover, porque não dá para desfazer com facilidade.

Alternativa: instalar a partir de uma cópia local

Use esta forma se você não tem internet, se o registro remoto falhar, ou se quiser instalar de uma cópia que já baixou. Clone só do GitHub (o mesmo host oficial do marketplace).

Primeiro, no terminal comum, baixe o repositório:

git clone https://github.com/petrinhu/bigtech_plugin

Depois, no Claude Code, registre o marketplace apontando para a pasta baixada e instale:

/plugin marketplace add <caminho-da-pasta-baixada>
/plugin install bigtech

Troque <caminho-da-pasta-baixada> pelo caminho completo da pasta onde você baixou o repositório (a pasta que contém o arquivo .claude-plugin/marketplace.json).

Compatibilidade

  • Plataforma. Funciona em Linux, macOS e Windows (nativo ou WSL). Os hooks são Python puro e rodam de forma cross-platform; a única exigência é que o python3 esteja alcançável (veja o Passo 0). Fora isso, não é preciso nenhuma configuração específica do SO.
  • As ferramentas dos agents são tratadas automaticamente. Quando um agent precisa de uma ferramenta externa (para um teste, um scan, um diagrama), ele instala sozinho as pequenas, sem permissão, e pergunta antes de qualquer instalação que precise de direitos de administrador, sempre escolhendo o comando certo para o seu SO. Você não pré-instala uma caixa de ferramentas; nada é instalado em silêncio.
  • Incompatível com o plugin caveman. O caveman encurta e comprime a comunicação, o que conflita com o reforço de modo do bigtech. Se você usa o caveman, desative-o antes de usar o bigtech. O hook de início de sessão avisa quando detecta os dois ativos ao mesmo tempo.
  • Dependências sugeridas (opcionais): playwright e superpowers. Não são obrigatórias, mas habilitam a experiência completa. Elas são instaladas pelo Claude Code (com comandos de barra), do mesmo jeito em todo sistema operacional, não pelo gerenciador de pacotes do seu sistema. O hook de início de sessão sugere instalá-las quando estão ausentes.
  • Para trabalho de UI/design: instale também a skill frontend-design da Anthropic, se ainda não estiver instalada. Ela ajuda a produzir design visual distintivo em vez de modelos genéricos. No Claude Code, rode /plugin marketplace add anthropics/skills e depois /plugin install example-skills@anthropic-agent-skills. É opcional (o agente frontend-engineer já embarca esses princípios), mas recomendada.

Segurança

Os hooks deste plugin executam código no seu computador. Em especial, o hook tdd-runner roda o comando de teste declarado pelo projeto que você abrir. Isso tem a mesma confiança de rodar make test ou npm test em um repositório: o comando vem de um arquivo do próprio projeto.

Antes de usar o plugin em repositórios de terceiros que você não conhece, confira qual comando de teste está configurado no arquivo .claude/tdd-guard.json do projeto. Para desligar o controle de TDD durante uma sessão, defina a variável de ambiente TDD_GUARD=off no terminal. O documento SECURITY.md do repositório traz o detalhe completo.

Próximo passo: aprenda o Uso no dia a dia. Voltar para a Home.

Clone this wiki locally