Construa Mods de Workspace IDE para o Claude Code

Isso vai transformar seu terminal em um app claude code ultra-rápido <role> Você é um engenheiro sênior de TypeScript. Você cria mods para Claude Code. Você escreve módulos pequenos, testa cada módulo e relata apenas resultados que você verificou. </role> <variables> AUTHOR_NAME = "Seu nome público" MARKETPLACE = "nome-do-seu-marketplace" LICENSE = "MIT" PANE_COLUMNS = 48 </variables> <context> Um mod é um plugin do Claude Code. O arquivo hooks/hooks.json nomeia um módulo de hooks. O módulo de hooks exporta register(on, options). Cada hook é on('event', matcher, async ($, e, next) => result). "$" é a API de mods. "e" é o evento. "next(e)" executa os outros mods e depois o Claude Code. Eu quero um espaço de trabalho estilo IDE dentro de uma sessão de terminal do Claude Code. As pessoas leem arquivos, pesquisam, veem diffs, executam tarefas e alternam entre sessões sem uma segunda janela. Outras pessoas instalarão esses mods de um marketplace público, então os mods devem carregar em uma máquina limpa e não devem falhar quando uma ferramenta (git, rg, cargo) estiver ausente. Documentação oficial (leia as páginas que você precisar): - https://t.co/i4akoKobgO - https://t.co/WPCOsxEplS - https://t.co/IeRIo28W71 - https://t.co/bQM1hlDd5j - Código-fonte do mod embutido: https://t.co/XYpFTigXbE (leia "diff" primeiro; é um painel com botões e rolagem própria) </context> <source_of_truth> A API de mods muda entre versões. Use esta ordem quando duas fontes discordarem: 1. As declarações de tipo que o Claude Code escreve em .claude-plugin/types/ de cada mod. Elas descrevem a versão instalada. 2. A saída de "claude plugin validate". 3. As páginas de documentação. 4. Este prompt. Execute /plugin-authoring antes de escrever código. Leia claude-code/index.d.ts antes de usar um evento, um método, um elemento ou uma prop. Pesquise o nome nesse arquivo. Não use um nome que não esteja nesse arquivo. Se este prompt nomear algo que a versão instalada não tem, não invente um substituto. Construa a versão mais próxima que a API suporta e registre a diferença em LIMITS.md. </source_of_truth> <api_rules> O Claude Code faz análise estática no módulo de hooks. Estas regras mantêm a validação verde: - Escreva cada chamada de API por extenso: $.fs.read(...), $.ui.open(...). Não atribua "$" ou um namespace a uma variável. Não desestruture "$". - Passe "$" apenas para uma função declarada no nível superior do mesmo arquivo. Não passe "$" para uma função importada, um método ou uma função definida dentro de um hook. - Escreva cada nome de evento como uma string literal em on(...). Não faça loop sobre uma lista de nomes de eventos. - Não declare uma segunda variável chamada "on" dentro de register. - Use módulos ES. Use declarações de import no topo do arquivo. Sem require. Sem import() dinâmico. - Importe apenas arquivos dentro do diretório do plugin, por caminho relativo. O único import puro é "claude-code". - Não comece um nome de plugin com "claude-". Resultado: mantenha cada chamada "$" no módulo de hooks. Coloque a lógica pura (parsers, modelo de árvore, ranking de busca, formatadores) em arquivos separados que recebem dados simples e retornam dados simples. Teste os arquivos puros diretamente. Limites para projetar: - Um hook tem 10 segundos de seu próprio tempo de execução. - $.fs.read e $.fs.write: 4 MiB para um arquivo. Uma string Text e um elemento Code: 10.000 caracteres. Pagine arquivos longos. - $.store: 4 MiB de JSON no total, compartilhado por todas as sessões na máquina. Dê a cada item sua própria chave. Limite cada lista. - $.process.run: 30 segundos por padrão. - Redraws: 30 por segundo para o painel visível, 10 para outros locais. - Um painel que um mod abre por conta própria aparece apenas em 144 colunas ou mais. Um painel que um comando de usuário ou pressionamento abre aparece em cada largura. Abra painéis a partir de comandos e pressionamentos. Regras de teclado: - Um mod não pode vincular Tab ou as setas do teclado. Tab move entre controles. Up e Down movem entre controles ou rolam. - Um hotkey de botão é um dígito ou uma letra minúscula. Enquanto um Input tem o foco, cada tecla imprimível vai para o Input. - Dê a cada controle uma tecla única. Os testes pressionam controles por tecla. - O Claude Code não tem elemento de abas. Desenhe abas como uma linha de botões simples. Estado: - Variável de módulo: perdida a cada recarregamento. Use para valores que podem ser perdidos. - $.state: dura pela sessão e redesenha os locais que leem o valor. Declare cada valor em types/index.d.ts e nomeie esse arquivo no manifesto. - $.store: dura entre sessões. Use para configurações, sessões recentes e projetos. </api_rules> <repository_layout> .claude-plugin/marketplace.json uma entrada para cada plugin, nome do marketplace = MARKETPLACE plugins/file-explorer/ plugins/workspace/ plugins/ide-usage/ plugins/ide-statusbar/ README.md LICENSE PROGRESS.md LIMITS.md tests.json Cada plugin: .claude-plugin/plugin.json nome, versão 0.1.0, descrição, autor = AUTHOR_NAME, licença = LICENSE, types quando necessário hooks/hooks.json { "modules": ["./register.ts"] } hooks/register.ts o único arquivo que chama "$" hooks/lib/*.ts lógica pura types/index.d.ts PluginState e qualquer namespace que o mod adiciona tests/*.test.ts testes para "claude plugin test" </repository_layout> <mod name="file-explorer"> Comando: /explorer abre o painel (id "explorer", título "Explorer", foco true, colunas PANE_COLUMNS). Registre o comando com immediate: true para que funcione durante um turno. Um segundo /explorer fecha o painel. /explorer <caminho> abre esse caminho. Linha de cabeçalho: a palavra EXPLORER, depois Back, Forward, Up, Close. Back e Forward movem pelo histórico de pastas e arquivos abertos. Um Input abaixo do cabeçalho. Seu propósito muda com a aba: - Aba Files: placeholder "Find files". Enter pesquisa nomes de arquivos e caminhos abaixo da raiz. A pesquisa ignora maiúsculas/minúsculas. Pare em 500 correspondências e mostre: N arquivos correspondem a "consulta" (primeiros 500, varredura interrompida). Mostre as correspondências como uma árvore com suas pastas pai. Marque o texto correspondido. Uma consulta vazia restaura a árvore. - Aba Code: placeholder "Find in file, :line, or /regex/". Texto simples encontra cada ocorrência. ":42" vai para a linha 42. "/re/" usa uma expressão regular. Mostre "correspondência 2 de 5". Os botões n e p vão para a próxima e a correspondência anterior. Abas: Files, Code, Diff. Aba Files: - Linha raiz: o nome da pasta raiz e o caminho completo. A primeira raiz é a pasta de trabalho da sessão. Up move a raiz para a pasta pai. - Linha de ação: New File, New Folder, Refresh, Collapse, More. New File e New Folder pedem um nome com um Input e criam o item na pasta selecionada. More contém Rename, Delete, Copy path e Show hidden files. Delete pede confirmação com $.ui.ask. - Árvore: leia um nível de pasta quando o usuário abre essa pasta. Classifique primeiro as pastas, depois os arquivos, por nome. Mostre um marcador para o estado da pasta, uma tag curta de tipo para tipos de arquivo conhecidos (json, md, ts, js, py, rs, go, sh) e "nome → alvo" para um link simbólico. Mostre "(empty)" em uma pasta vazia. Pule .git e node_modules, a menos que arquivos ocultos estejam ativados. - Seleção e paginação: uma linha selecionada. Os botões movem a seleção para cima e para baixo, abrem uma pasta, fecham uma pasta e abrem um arquivo. Mostre o intervalo, por exemplo "7-49 de 329". Desenhe apenas as linhas que cabem em e.props.scroll.bodyRows. Aba Code: - Breadcrumb do caminho, depois "N linhas · tamanho". - Números de linha e cores de sintaxe. Use o elemento Code. Pagine o arquivo para que nenhum elemento seja maior que 10.000 caracteres. - Para um arquivo maior que 4 MiB ou um arquivo binário, mostre o tamanho e uma mensagem. Não leia o arquivo. - Destaque a correspondência atual e a linha atual. Aba Diff: - Mostre o diff não confirmado do arquivo aberto (git diff para esse caminho). Use o elemento Code no modo diff. - Mostre a contagem de linhas adicionadas e removidas. - Quando o Claude edita um arquivo com Edit, Write ou MultiEdit, registre o caminho no hook https://t.co/Lb6btDn0iW após next(e) retornar. Se o painel estiver aberto, selecione esse arquivo e mostre a aba Diff. Não abra o painel por conta própria. - Se a pasta não for um repositório git, diga isso em uma linha. Outros mods abrem um arquivo por meio de um namespace que este mod adiciona à API de mods: https://t.co/crzRXVIH3H({ path, line, tab }). Declare o namespace em types/index.d.ts. Leia o mod embutido "telemetry" para ver como um mod adiciona métodos para outros mods. </mod> <mod name="workspace"> Depende de file-explorer (liste-o em dependencies no plugin.json). Comando: /workspace abre o painel do navegador (id "workspace", título "Workspace", colunas PANE_COLUMNS). Posicionamento do navegador: a posição documentada de um painel é um dock ao lado da transcrição, e o Claude Code dá a cada painel aberto uma aba com seu título. Pesquise nos tipos um campo que coloque um painel no lado esquerdo. Se existir, coloque o navegador à esquerda e as ferramentas no dock direito. Se não existir, o navegador é mais um painel no dock. Registre o resultado em LIMITS.md. Conteúdo do navegador, de cima para baixo: 1. Título CLAUDE CODE e um botão New chat. New chat executa o comando embutido que inicia uma nova conversa. Encontre o nome do comando com $.command.list. 2. WORKSPACE: um botão para cada ferramenta, nesta ordem: Files, Terminal, Browser, Source Control, Problems, Run Tasks, Outline, To-do Comments, Timeline, Usage, Model Router. Um pressionamento abre esse painel de ferramenta e dá a ele o foco. Marque as ferramentas que estão abertas. 3. RECENTS: as 5 sessões mais recentes, com "Show more". Cada linha mostra o título, o nome do projeto e a idade (8m, 22h, 3d). O título é o primeiro prompt da sessão, cortado para caber. Um pressionamento em uma linha mostra os prompts dessa sessão abaixo da linha. Marque a sessão atual. 4. PROJECTS: cada pasta de projeto com sua contagem de sessões. Um pressionamento mostra as sessões desse projeto. Índice de sessão: no hook prompt.submit, escreva { id, cwd, repo, title, prompts[], updatedAt } em $.store sob a chave "session:<id>". Mantenha os 50 prompts mais recentes para cada sessão e as 200 sessões mais recentes. Leia o store novamente antes de cada escrita, porque outras sessões escrevem no mesmo store. Não leia nem analise os arquivos de transcrição do próprio Claude Code. Abrir uma sessão recente: verifique nos tipos um método suportado para alternar ou retomar uma sessão. Se não existir, copie "claude --resume <id>" com $.ui.copy e mostre um toast dizendo isso. Ferramentas. Cada ferramenta é um painel com seu próprio id, um título curto e um botão Refresh. Cada ferramenta mostra uma linha clara quando não tem dados ou quando seu programa está ausente. 1. Files: chama https://t.co/crzRXVIH3H com a pasta da sessão. Não desenha uma segunda árvore. 2. Terminal: um Input que executa um comando com $.process.spawn na pasta da sessão. Transmita a saída para o painel. Mantenha as últimas 500 linhas. Mostre o código de saída. Mantenha um histórico de 50 comandos. Um botão Stop encerra o processo. Este é um executor de comandos, não um emulador de terminal; diga isso no README. 3. Browser: um Input para uma URL. Busque com $.http.fetch. Mostre o código de status, o título da página e o texto legível como Markdown, cortado para o limite do elemento. Mostre links como botões que carregam o link. Um botão "Open in system browser" usa o comando open do sistema operacional. Permita apenas http e https. 4. Source Control: branch, contagens ahead e behind, e os arquivos alterados com status e "+adicionadas −removidas" do git. Um pressionamento em um arquivo chama https://t.co/crzRXVIH3H com a aba "diff". Botões: Stage, Unstage, Stage all. Um Input de commit confirma os arquivos preparados após uma confirmação com $.ui.ask. Não faça push, pull, reset ou descarte de alterações. 5. Problems: execute o comando de verificação do projeto e liste cada problema como "arquivo:linha mensagem" com uma marca de gravidade. Detecte o comando: tsc --noEmit para tsconfig.json, cargo check para Cargo.toml, go vet para go.mod, ruff check para pyproject.toml quando ruff estiver instalado. Uma configuração de usuário substitui o comando detectado. Um pressionamento chama https://t.co/crzRXVIH3H com a linha. Execute apenas no Refresh e após um turno terminar, e não execute duas verificações ao mesmo tempo. 6. Run Tasks: mostre a pasta da sessão. Encontre tarefas em scripts package.json, alvos Makefile, receitas justfile, Cargo.toml (build, test, clippy), scripts pyproject.toml e go.mod (build, test, vet). Se nenhum for encontrado, mostre: Nenhuma tarefa encontrada (package.json, Makefile, justfile, Cargo.toml, pyproject.toml, go.mod). Um botão para cada tarefa. Um Input com o placeholder "Run a command, then Enter". Transmita a saída e mostre o código de saída e o tempo. 7. Outline: os símbolos do arquivo que está aberto no explorer, com números de linha: funções, classes, structs, interfaces, constantes e cabeçalhos Markdown. Use uma pequena tabela de padrões para cada linguagem (ts, js, py, rs, go, md). Recue símbolos aninhados. Um pressionamento chama https://t.co/crzRXVIH3H com a linha. 8. To-do Comments: encontre comentários TODO, FIXME, HACK e NOTE no projeto. Use rg quando estiver instalado. Se não, percorra a árvore com $.fs.list e pule .git, node_modules, target e dist. Agrupe por tag. Mostre "arquivo:linha texto". Limite a 300 itens. Um pressionamento chama https://t.co/crzRXVIH3H com a linha. 9. Timeline: uma linha para cada prompt, chamada de ferramenta e fim de turno nesta sessão, mais recente primeiro, com a hora do relógio. Para Edit e Write, mostre o caminho e as contagens de linhas. Um pressionamento em uma linha de edição chama https://t.co/crzRXVIH3H com a aba "diff". Mantenha 300 linhas. 10. Usage: leia $.session.usage(). Mostre a porcentagem de contexto, tokens e janela com uma barra. Mostre cada limite de taxa com porcentagem usada e tempo de redefinição. Mostre o custo se o campo tiver um valor. Registre a contagem de tokens de cada turno no hook session.measure e desenhe os últimos 30 turnos como um pequeno gráfico de barras. Use Raster no terminal e texto em outras superfícies (verifique e.surface). 11. Model Router: mostre o modelo da sessão principal e cada início de subagente com seu tipo, seu modelo e seu estado. Três modos em um Select: Off, Suggest, Auto. Off apenas registra. Suggest mostra o modelo que as regras selecionam e não muda nada. Auto define o modelo de um subagente no hook agent.spawn a partir de uma tabela de regras (tipo de subagente ou palavra-chave de tarefa → modelo) que o usuário edita no painel e que é salva em $.store. Regras: nunca mude o modelo da sessão principal, mantenha um modelo que o chamador nomeou e deixe o início continuar inalterado se uma regra falhar. Leia os nomes dos modelos da sessão e das configurações. Não escreva nomes de modelos no código. O modo padrão é Off. </mod> <mod name="ide-usage"> Uma linha de status com $.ui.status: "ctx 20% · <modelo>". Atualize-a no hook session.measure. Sem painel. </mod> <mod name="ide-statusbar"> Uma linha de status com $.ui.status: "<linguagem> · <nome do arquivo>" para o arquivo que está aberto no explorer, ou o arquivo que o Claude leu ou editou por último. Derive a linguagem da extensão do arquivo. Mostre "Plain Text" para uma extensão desconhecida. Sem painel. </mod> <out_of_scope> - Abas de janela para mais de uma sessão (por exemplo ⌘1 e ⌘2). O aplicativo de terminal desenha essas. Um mod não pode. - Um editor de texto completo no painel. Um Input é uma linha. - Alterações no prompt de permissão. Um mod não pode desenhar lá. Não adicione recursos que não estão neste prompt. Não adicione opções de configuração que nenhum recurso precisa. </out_of_scope> <safety> Um mod executa com as permissões do usuário e não é isolado. Escreva código que um revisor cuidadoso aceite: - Confirme com $.ui.ask antes de excluir, renomear e confirmar. - Nunca execute um comando git destrutivo. Nunca aprove uma chamada de ferramenta para o usuário. Nunca envie conteúdo de arquivo ou prompts para a rede. A ferramenta Browser busca apenas a URL que o usuário digitou ou pressionou. - Não leia variáveis de ambiente ou configurações que um recurso não precisa. "claude plugin validate" lista leituras e chamadas de env; mantenha essa lista curta. - Passe argumentos para $.process como uma matriz. Não construa uma string de shell a partir de nomes de arquivo. Durante esta construção, edite arquivos apenas dentro deste repositório. Não faça push. Não instale os plugins nas minhas configurações de usuário. Pergunte-me antes de qualquer ação que seja difícil de desfazer. </safety> <workflow> Esta tarefa é longa. Seu contexto é compactado automaticamente, então não pare cedo para economizar tokens. Mantenha o estado em arquivos para que um novo contexto possa continuar: - PROGRESS.md: o que está feito, o que vem a seguir e cada decisão com seu motivo. - tests.json: uma entrada para cada teste de aceitação com o status not_started, failing ou passing. - LIMITS.md: cada recurso que a API instalada não pode fazer e o que você construiu em seu lugar. - Um commit git para cada recurso que passa. No início de cada novo contexto: leia PROGRESS.md, tests.json, LIMITS.md e o log do git. Execute a suíte de testes antes de adicionar um recurso. Fase 0, descubra. Execute /plugin-authoring. Execute "claude --version". Leia as páginas de documentação e o mod embutido "diff". Em seguida, escreva PLAN.md: os eventos e métodos que cada recurso usa, com a linha dos tipos que prova que cada um existe. Liste cada recurso que precisa de um design diferente. Mostre-me PLAN.md e continue, a menos que eu objete. Fase 1, scaffold. Crie o layout do repositório, os quatro manifestos, arquivos hooks.json e arquivos register.ts vazios que registram apenas seus comandos. Execute "claude plugin validate --strict" em cada plugin até passar. Em seguida, pare e me dê este comando para reiniciar com hot reload: claude --plugin-dir ./plugins/file-explorer --plugin-dir ./plugins/workspace --plugin-dir ./plugins/ide-usage --plugin-dir ./plugins/ide-statusbar Depois que eu digitar "continue", leia os tipos gerados em .claude-plugin/types/ e corrija PLAN.md. Fase 2, file-explorer. Construa nesta ordem: modelo de árvore e aba Files, pesquisa de arquivos, aba Code com localizar, aba Diff, https://t.co/crzRXVIH3H. Escreva os testes para um recurso antes de seu código. Fase 3, workspace. Construa o navegador e o índice de sessão primeiro. Em seguida, construa as ferramentas na ordem listada. Termine e teste uma ferramenta antes de começar a próxima. Fase 4, linhas de status. Construa ide-usage e ide-statusbar. Fase 5, lançamento. Escreva marketplace.json, LICENSE e README.md. O README fornece: o que cada mod faz, os comandos de instalação (claude plugin marketplace add, claude plugin install <nome>@MARKETPLACE), a versão do Claude Code que você testou, os comandos, os hotkeys, o que cada mod pode alcançar (das linhas "hooks:" e "calls:" do validate) e o conteúdo de LIMITS.md. Execute a verificação completa. Trabalhe diretamente. Use um subagente apenas para uma pesquisa em muitos arquivos que não precise do seu contexto. </workflow> <tests> Os testes são executados com "claude plugin test" e não precisam de sessão nem rede. Um teste dispara eventos, pressiona controles por tecla e verifica o desenho ou o resultado. Stub $.fs, $.process, $.http e $.store. Escreva testes que verifiquem o comportamento, por exemplo: - Uma pesquisa por "auth" em uma árvore stub retorna os arquivos corretos, marca o texto correspondido e para em 500. - ":42" seleciona a linha 42. "/re(fresh)?/" encontra as correspondências corretas. Uma expressão regular inválida mostra uma linha de erro e não lança. - Um pressionamento em uma linha de Source Control chama https://t.co/crzRXVIH3H com a aba "diff". - Run Tasks sem arquivo de manifesto mostra a linha "Nenhuma tarefa encontrada". - Um programa git ausente dá uma linha clara e nenhum erro. - O índice de sessão mantém 200 sessões e mescla com uma escrita mais recente de outra sessão. - Model Router no modo Off e no modo Suggest retorna next(e) inalterado. Escreva código geral que seja correto para cada entrada válida. Não escreva código que apenas satisfaça um teste. Não exclua nem enfraqueça um teste para fazê-lo passar. Se um teste estiver errado ou um recurso não for possível, me diga. </tests> <done_when> 1. "claude plugin validate --strict" passa para cada plugin. 2. "claude plugin test" passa para cada plugin, e tests.json não tem nenhuma entrada failing ou not_started. 3. "tsc -p" em cada plugin não relata nenhum erro contra os tipos gerados. 4. Cada comando responde em "claude -p" (por exemplo: claude -p "/explorer" --plugin-dir ./plugins/file-explorer) sem erro. 5. LIMITS.md lista cada diferença deste prompt. 6. Você me dá uma lista de verificação dos itens que apenas uma pessoa pode verificar em uma sessão ao vivo: cada painel abre, os hotkeys funcionam e o layout cabe em 110 e em 144 colunas. </done_when> <reporting> Após cada fase, escreva um relatório curto: o que você construiu, os comandos exatos que você executou, seus resultados e o que não está verificado. Separe "os testes passam" de "eu vi funcionar em uma sessão". Se você não executou algo, diga que não executou. </reporting> [fim do prompt]