Not translated yet
This page is not available in English yet. Showing the Português version.
Plugins e ferramentas
Ferramentas em TypeScript em .hinow/tools e plugins com ganchos em .hinow/plugins.
Updated on Sep 16, 2026
Quando um comando ou uma skill não bastam, dá para estender o HiNow Code com código. De um lado, ferramentas que o agente chama como chama as suas. De outro, plugins que reagem ao que acontece: uma ferramenta vai rodar, uma sessão terminou, uma permissão foi pedida. Tudo em TypeScript, carregado quando o programa abre.
import { tool } from "@hinow-ai/plugin"
export default tool({
description: "Retorna a data e hora atual da máquina onde o HiNow Code roda",
args: {},
async execute() {
return new Date().toISOString()
},
})O nome do arquivo é o nome da ferramenta (hora). Com argumentos, descreva-os com tool.schema (é o zod):
import { tool } from "@hinow-ai/plugin"
export default tool({
description: "Consulta um pedido pelo número na API interna da loja",
args: { numero: tool.schema.string().describe("número do pedido, ex. 10234") },
async execute({ numero }, ctx) {
const res = await fetch(`https://api.interna/pedidos/${numero}`)
return { title: `pedido ${numero}`, output: await res.text() }
},
})ctx traz directory, worktree, sessionID, agent, abort e ctx.ask(...) para pedir permissão à pessoa antes de algo sensível. Um arquivo pode exportar várias ferramentas (export const buscar = tool(…) vira pedido_buscar). Se um arquivo não carregar (erro de sintaxe, import errado), ele é pulado com um aviso no log e o resto continua.
import type { Plugin } from "@hinow-ai/plugin"
import { appendFile } from "node:fs/promises"
export const Auditoria: Plugin = async ({ directory }) => ({
"tool.execute.before": async (input) => {
await appendFile(directory + "/auditoria.log", `${new Date().toISOString()} ${input.tool}\n`)
},
})Tudo em .hinow/plugins/ (ou ~/.config/hinow/plugins/) é carregado sozinho. O plugin recebe client (a API do HiNow Code), project, directory, worktree e $ (o shell do Bun) e devolve os ganchos que quer:
| Gancho | Quando roda |
|---|---|
event | Em todo evento: sessão criada, mensagem, ferramenta, permissão… |
config | Uma vez, com a configuração somada: dá para alterar campos |
chat.message, chat.params, chat.headers | Antes de cada mensagem ir ao modelo |
tool.execute.before, tool.execute.after | Antes e depois de cada ferramenta (dá para mudar os argumentos ou a saída) |
permission.ask | Quando uma permissão vai ser pedida: pode responder allow, deny ou deixar perguntar |
shell.env | Variáveis de ambiente dos comandos |
tool | Um objeto { nome: tool(…) } com ferramentas que o plugin adiciona |
Você não instala nada: o próprio HiNow Code grava um pacote @hinow-ai/plugin mínimo em .hinow/node_modules/ (e em ~/.config/hinow/node_modules/) ao abrir, com a versão do programa, e o .gitignore da pasta já o ignora. O editor enxerga os tipos e o runtime encontra o módulo. Se a sua ferramenta precisa de bibliotecas do npm, crie um package.json em .hinow/ com as dependências: elas são instaladas em segundo plano.
"plugin": ["hinow-cli-notify", "hinow-cli-lint@1.2.0", "./ferramentas/meu-plugin.ts"]hinow-cli plugin <módulo> instala e adiciona à configuração. hinow-cli --pure (ou HINOW_PURE=1) abre sem nenhum plugin externo, para isolar um problema.
É código seu rodando
Plugins e ferramentas rodam dentro do processo, com as suas permissões, antes de qualquer pergunta ao usuário. Revise o que instala e não commite segredos nos arquivos.