StickShift é um painel de menu-bar em macOS com um H-pattern de câmbio de verdade: puxe o manche pra trocar o modelo do Claude Code ou Codex na pane de terminal que você está olhando, arraste o acelerador pra trocar o effort. Tudo é provado antes de agir — ou recusa com um motivo, nunca digita às cegas.
Nada de editar config na mão ou decorar comando: StickShift lê a pane pela Accessibility API do
macOS, prova que é um agente local idle e digita exatamente o que você digitaria — /model,
/effort, ou as teclas do picker do Codex.
Nunca edita arquivo de config, nunca chama API de provider, nunca usa automação de terminal. Só digita depois de provar pane idle, processo local certo e binário assinado e qualificado — qualquer prova que falhar vira recusa com código de motivo.
Face Claude (throttle até ULTRACODE) e face Codex (throttle até ULTRA), com os labels exatos de cada provider e atalhos globais (Cmd+Shift+1..5, Cmd+Shift+R) que disparam a marcha sem nem abrir o painel.
bin/shift faz dry-run por padrão (não digita nada);
--commit executa de fato. shift doctor diagnostica permissão, config e atribuição
da pane focada num comando só.
Entre puxar a marcha e o toast CHANGED, o motor passa por uma cadeia de provas — qualquer elo que falhar interrompe a troca e devolve um código de motivo em vez de um keystroke.
A pane focada é lida via Accessibility API; um classificador puro extrai agente, modelo, effort, cwd, e se está idle/busy/com diálogo aberto, com composer provadamente vazio.
A pane é ligada a um processo local (tty → foreground group → cwd), e o binário atribuído tem assinatura, team e versão checados contra o manifesto.
Digita com keycodes resolvidos pelo layout atual, prova a entrega por delta de ocorrência antes de qualquer Enter, e só reporta sucesso com verdicto ancorado no fim da pane.
O caminho automático (setup.sh) cobre quase tudo; isso aqui é o que precisa existir
na máquina antes.
Precisa do clang pra compilar.
# instala as command line tools se faltar
xcode-select --installWarp é o default verificado ponta a ponta. Terminal.app já passou nos dois testes mais difíceis; outros terminais se qualificam em 4 passos.
# qualifica um terminal novo
./scripts/qualify-terminal.sh "iTerm"StickShift pede a permissão sozinho no primeiro lançamento — é só conceder em System Settings quando o diálogo aparecer.
# confirma o que está concedido
./bin/shift doctorO script é idempotente: roda de novo sem medo se algo falhar no meio.
Verifica pré-requisitos, cria a identidade de assinatura estável, builda, roda a suíte de testes inteira,
instala em ~/Applications/StickShift.app e já abre o app.
git clone https://github.com/inematds/stickshift && cd stickshift # baixa o repo ./scripts/setup.sh # idempotente, instala tudo
Habilite o StickShift em System Settings → Privacy & Security → Accessibility. Depois saia e abra o app de novo (clique direito no gear do menu-bar → Quit → reabra) — a permissão só gruda no processo depois do relaunch, esse é o erro de suporte nº 1.
Clique no pane do terminal rodando o agente, arraste o manche até um gate (ou dispare pela CLI a partir de
outro pane — a CLI recusa a própria pane como SELF_TARGET).
./bin/shift 4 # dry run: mostra o plano, não digita nada ./bin/shift 4 --commit # executa de verdade
CHANGED quer dizer que deu certo; qualquer outro código é uma recusa explicada — cada
tentativa fica registrada com motivo, nunca com o conteúdo da pane.
tail -5 ~/.stickshift/log
Aponte Claude Code, Codex, ou qualquer agente de código pra este repo e diga
"set up StickShift on this Mac". O AGENTS.md do repo é o playbook operacional
completo: instalação, adaptação a terminal e versão de agente, e debug de recusa por código de motivo.
O motor é construído sobre três pilares específicos de macOS — leitura de pane via Accessibility API, injeção de tecla via CGEvent e permissões TCC — e nenhum dos três existe do mesmo jeito no Windows. Isso não é uma limitação de descuido: é uma escolha documentada, com o mapa completo de portabilidade já escrito no próprio repositório.
O README.md documenta cada invariante de segurança (por que o painel nunca pode virar
key window, por que a entrega precisa de prova por delta de ocorrência, etc.) e o docs/WINDOWS.md
já traz a avaliação completa de porte: o que aproveita sem mudar (o classificador de pane, os planos de
protocolo, a máquina de estados — tudo funções puras sobre strings), o que precisa ser reconstruído
(UI Automation no lugar de Accessibility, SendInput no lugar de CGEvent, atribuição de pane
via árvore UIA do Windows Terminal no lugar de tty/processo do macOS) e a ordem de spikes que reduz o
risco mais rápido.
Com o repo clonado no Windows, abra seu agente de código (Claude Code, Codex, ou outro) e peça pra ele
ler README.md, AGENTS.md e docs/WINDOWS.md, fazer a engenharia
reversa da lógica (o classificador em src/core/AXState.m, o motor de estados em
src/core/Switch.m, os planos em src/core/Protocol.m) e construir uma versão
adaptada pra Windows a partir daí — trocando UIA + SendInput no lugar das APIs de macOS, seguindo a ordem
de spikes sugerida no próprio docs/WINDOWS.md.
Direto de docs/: a anatomia de uma troca e o mapa de código-fonte, do jeito que
acompanham o README.
Do jeito que o próprio README documenta hoje.
scripts/qualify-terminal.sh; reduzir a ambiguidade que hoje depende de título de janela + geometria + cwd.docs/WINDOWS.md.