# Matraca

Agente de inteligência artificial para **Telegram** e **WhatsApp**. Roda no seu computador, você usa pelos apps dos canais. Ele lida com arquivos, executa comandos no shell, extrai texto de páginas da web e possui um sistema de habilidades extensível compatível com [Agent Skills](https://agentskills.io/).

## Instalação

```bash
uv tool install matraca
```
[Node.js](https://nodejs.org/) instalado no sistema é necessário para o canal WhatsApp.

## Uso

```bash
matraca telegram   # inicia o canal Telegram
matraca whatsapp   # inicia o canal WhatsApp
```

Na primeira execução, o arquivo de configuração é criado em `~/.matraca/config.json`. Adicione as chaves do seu provedor de inteligência artificial, o nome que identifica o modelo e o token do bot (se Telegram).

## Contatos

Para garantir sua privacidade, o agente apenas responde a contatos previamente autorizados. O processo de autorização funciona da seguinte forma:

1. O usuário deve enviar uma primeira mensagem para o bot (pelo Telegram ou WhatsApp).
2. O bot registrará o contato no arquivo `~/.matraca/contacts.json`.
3. Abra o arquivo `~/.matraca/contacts.json` e altere `authorized` para `true`.

## Habilidades

Habilidades são extensões para o agente e seguem o padrão de [Agent Skills](https://agentskills.io/). Instale-as em `~/.matraca/skills/`.

Ao criar sua skill contendo scripts Python, use a declaração de dependências da [PEP 723](https://peps.python.org/pep-0723/). O agente executará o seu script de forma isolada em um ambiente gerenciado pelo [uv](https://docs.astral.sh/uv/).