convez.ai
AgenteAutomaçãoIntermediário
hxy91819

Agent Notify

hxy91819/agent-notify

Notificações Telegram para conclusões de agentes de código

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent que envia notificações compactas via Telegram quando agentes de código (Codex, Claude Code, Kimi) completam tarefas. Funciona como um binário Go leve, sem dependências de runtime, integrando-se aos hooks nativos dos agentes para capturar contexto (host, diretório, duração, prompt e resposta final).

Instalação

$npx convez-ai hxy91819/agent-notify

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.2.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Receber alertas instantâneos quando agentes de IA completam tarefas longas
  • Monitorar progresso de sessões Codex/Claude Code remotamente
  • Integrar feedback de agentes em workflows de desenvolvimento

Veredito

Ferramenta utilitária e bem executada para quem usa intensivamente agentes de código. A abordagem minimalista (sem diffs, sem logs verbosos) é sensata, mas o escopo é narrow — ideal apenas para developers que rodam Codex/Claude Code localmente e querem notificações Telegram.

README

A tradução para o português deste README ainda está na fila.

agent-notify

agent-notify sends compact completion notifications for coding agents.

Current support:

  • Agents: Codex, Claude Code, Kimi Code
  • Channel: Telegram
  • Distribution target: one small Go binary, no runtime dependencies

The default message is intentionally small: host, directory, time, the first sentence of the prompt, and the agent's final reply. Git repository, branch, and duration are included only when the agent exposes enough local context to determine them. Field labels include emoji for readability. It does not send diffs, command output, or logs.

Quick Start

Install the latest Linux/macOS release:

curl -fsSL https://raw.githubusercontent.com/hxy91819/agent-notify/main/scripts/install-release.sh | bash

This installs agent-notify to ~/.local/bin/agent-notify and configures both Codex and Claude Code hooks. Use --setup codex, --setup claude, --setup kimi, --setup all, or --setup none when you want a different install scope.

Build and install from this checkout:

bash scripts/install.sh

Then follow the prompts for your Telegram bot token and chat id. To let agent-notify read the latest chat id from Telegram after you message your bot:

TELEGRAM_BOT_TOKEN=123456:example bash scripts/install-release.sh --auto-chat-id --test

If you already know both values:

TELEGRAM_BOT_TOKEN=123456:example TELEGRAM_CHAT_ID=123456789 bash scripts/install-release.sh --test

Codex or Claude Code may ask you to review and trust the new hooks in /hooks the next time you start a session.

Manual Build

go build -o agent-notify ./cmd/agent-notify
./agent-notify --help

Manual setup:

./agent-notify setup codex-telegram \
  --bot-token "$TELEGRAM_BOT_TOKEN" \
  --chat-id "$TELEGRAM_CHAT_ID" \
  --bin "$(pwd)/agent-notify" \
  --test

Claude Code setup:

./agent-notify setup claude-telegram \
  --bot-token "$TELEGRAM_BOT_TOKEN" \
  --chat-id "$TELEGRAM_CHAT_ID" \
  --bin "$(pwd)/agent-notify" \
  --test

Kimi Code setup:

./agent-notify setup kimi-telegram \
  --bot-token "$TELEGRAM_BOT_TOKEN" \
  --chat-id "$TELEGRAM_CHAT_ID" \
  --bin "$(pwd)/agent-notify" \
  --test

This writes:

  • ~/.config/agent-notify/config.json
  • ~/.codex/hooks.json
  • ~/.claude/settings.json
  • ~/.kimi-code/config.toml

Existing Codex, Claude Code, and Kimi Code hooks are preserved. Installed hook commands include absolute --config, --state-file, and --log-file paths so they do not depend on the environment variables available inside a running agent session.

Release Downloads

GitHub Releases publish prebuilt archives for:

  • linux_amd64
  • linux_arm64
  • darwin_amd64
  • darwin_arm64

Each release includes checksums.txt for SHA-256 verification. Manual install:

tar -xzf agent-notify_v0.1.0_linux_amd64.tar.gz
install -m 755 agent-notify_v0.1.0_linux_amd64/agent-notify ~/.local/bin/agent-notify
agent-notify setup codex-telegram
agent-notify setup claude-telegram
agent-notify setup kimi-telegram

Remove installed hooks without touching unrelated hooks:

agent-notify setup remove-hooks --agent codex
agent-notify setup remove-hooks --agent claude
agent-notify setup remove-hooks --agent kimi
agent-notify setup remove-hooks --agent both
agent-notify setup remove-hooks --agent all

On macOS, if the downloaded binary is quarantined:

xattr -d com.apple.quarantine ~/.local/bin/agent-notify

Telegram Chat ID

The bot token identifies the bot. The chat id identifies where the bot should send messages.

  1. Open Telegram and send your bot a message.
  2. Run:
agent-notify setup codex-telegram --bot-token "$TELEGRAM_BOT_TOKEN" --auto-chat-id
agent-notify setup claude-telegram --bot-token "$TELEGRAM_BOT_TOKEN" --auto-chat-id
agent-notify setup kimi-telegram --bot-token "$TELEGRAM_BOT_TOKEN" --auto-chat-id

For group notifications, add the bot to the group, send a group message, and then use --auto-chat-id. Group chat ids are often negative.

Commands

agent-notify setup codex-telegram --help
agent-notify setup claude-telegram --help
agent-notify setup kimi-telegram --help
agent-notify setup remove-hooks --agent codex
agent-notify telegram test --dry-run
agent-notify telegram test
agent-notify codex cache < user-prompt-submit.json
agent-notify codex notify --dry-run < stop.json
agent-notify claude cache < user-prompt-submit.json
agent-notify claude notify --dry-run < stop.json
agent-notify kimi cache < user-prompt-submit.json
agent-notify kimi notify --dry-run < stop.json

Agent hook commands are designed to be non-blocking. Invalid hook JSON, missing Telegram config, or Telegram network failures are logged as warnings and exit successfully so the coding agent can finish normally.

Message fields:

  • Repo: git remote repository name, only when the current directory is in a git repository.
  • Branch: current git branch or detached@<sha>, only when available.
  • Duration: elapsed time between agent UserPromptSubmit and Stop hooks, only when the start hook was captured.
  • Result: last_assistant_message, capped by max_result_chars.

Hook diagnostics are written to:

~/.local/state/agent-notify/hook.log

Configuration

Default config path:

~/.config/agent-notify/config.json

Example:

{
  "telegram": {
    "bot_token": "123456:example",
    "chat_id": "123456789"
  },
  "defaults": {
    "max_prompt_chars": 120,
    "max_result_chars": 200,
    "timezone": "Asia/Shanghai"
  }
}

Environment variables override the file:

  • TELEGRAM_BOT_TOKEN
  • TELEGRAM_CHAT_ID

For migration, agent-notify also reads the earlier prototype file ~/.codex/telegram-notify.env when present.

Development

go test ./...
go build -o agent-notify ./cmd/agent-notify
golangci-lint run
bash scripts/lint-static.sh

scripts/lint-static.sh protects project-specific invariants that generic Go linters cannot infer, such as absolute hook paths, agent-scoped state keys, and safe stale-lock recovery.

Optional local git hooks:

cp scripts/hooks/secret-scan.sh .git/hooks/pre-commit
cp scripts/hooks/secret-scan.sh .git/hooks/pre-push
chmod +x .git/hooks/pre-commit .git/hooks/pre-push

The hook scans staged content before commit and tracked HEAD content before push for common credentials such as Telegram bot tokens, API keys, GitHub tokens, private keys, and sensitive env/config file paths.

The earlier Python prototype is kept under examples/codex-python-hook/ as a reference implementation. The supported CLI is the Go binary.

Simulate Codex hooks:

tmpdir=$(mktemp -d)
printf '%s\n' '{"telegram":{"bot_token":"dummy","chat_id":"123"},"defaults":{"max_prompt_chars":80,"timezone":"Asia/Shanghai"}}' > "$tmpdir/config.json"

printf '%s\n' '{"hook_event_name":"UserPromptSubmit","cwd":"/tmp/project","prompt":"First sentence. Second sentence.","session_id":"s1","turn_id":"t1"}' \
  | ./agent-notify codex cache --config "$tmpdir/config.json" --state-file "$tmpdir/state.json"

printf '%s\n' '{"hook_event_name":"Stop","cwd":"/tmp/project","session_id":"s1","turn_id":"t1"}' \
  | ./agent-notify codex notify --config "$tmpdir/config.json" --state-file "$tmpdir/state.json" --dry-run

Simulate Claude Code hooks by replacing codex with claude in the two commands above.

License

MIT

Ver o original no GitHub

Bom para

Relacionados