convez.ai
MCP ServerAutomaçãoAvançado
TGPSKI

Leather

TGPSKI/leather

Agentes IA locais em Go puro: scheduled jobs, webhooks e multi-agent pipelines

Ver no GitHub
BomPluginScore · de 0 a 100

Infraestrutura de agentes locais em um único binário Go sem dependências externas. Executa agentes declarativos com suporte a jobs agendados, webhooks, tool calling e auditoria completa de execuções, rodando localmente sem control plane hospedado.

Instalação

$npx convez-ai TGPSKI/leather

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
17
Forks
0
Acompanhando
2
Saúde
100%
Último commit
há 4 semanas
Versão
v0.5.4
Issues abertas
4
Contribuidores
1

Casos de uso

  • Automação de workflows com agentes IA locais
  • Processamento de webhooks para múltiplos agentes
  • Jobs agendados com auditoria e replay determinístico
  • Integração com servidores MCP e ferramentas CLI
  • Análise de PRs e processamento de dados estruturados

Veredito

Solução robusta para quem quer agentes IA sem dependências pesadas ou serviços hospedados. Ideal para deployments on-premise e workstations, com tooling maduro para debugging e auditoria de execuções.

README

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

leather

Go Reference Go Version License GitHub Release CI

Local agent infrastructure in one stdlib-only Go binary.

Leather runs declarative agents on your workstation, server, or Raspberry Pi: scheduled jobs, one-shot runs, webhook-driven workflows, tool calling, and auditable outputs.

No Python stack. No hosted control plane. No broker, telemetry, or dependency pile.

leather run ~/.leather/agents/summarizer.agent.md
leather serve --pretty --stats
leather ingest pr.json --kind github.pr --curing pr-review

Why leather

Instead of…leather gives you
A Python stack, a virtualenv, and a requirements.txt you re-pin every quarterOne Go binary. Stdlib only. go.mod has zero require entries.
A hosted control plane or always-on SaaSA single process you run on your workstation, server, or Raspberry Pi. No phone-home. No telemetry. Loopback API by default.
A heavy broker (Redis, RabbitMQ, Temporal) just to fan webhooks into agentsBuilt-in queues with backpressure, retries, and dead-letter routing. HMAC-validated webhook intake. Same process.
Writing a Python plugin every time an agent needs a toolSkills, toolsets, MCP servers, and a shell-manifest companion binary — all stdlib Go.
"Context window exceeded" halfway through a multi-megabyte PROversized inputs are paged into bounded cuts; the model only ever sees what fits.
Grepping yesterday's logs to reconstruct what an agent actually didJSONL run history, deterministic replay, lineage on every artifact (agent, curing, input hide, timestamps).
Picking between a cron tool and a workflow engineScheduled agents and webhook-driven multi-agent pipelines, in one binary, side by side.

Examples

Every example is a single make target. Copy the env template, point it at your local model, and go:

cp examples/env.example examples/.env
$EDITOR examples/.env
make example-02
make example-06

The full catalog lives in examples/ — thirteen runnable mainline demos from hello-mock to a concurrent git workflow, plus dedicated RPi/Hailo examples.

Capabilities

Local agent runtime

Agents are Markdown + YAML. They run against any OpenAI-compatible endpoint. Token budgets are tracked per request; context is summarized or truncated before the model's limit is hit.

Tools, skills, MCP, and shell

  • Skills (*.skill.yaml) define tools plus optional prompt/parameter metadata.
  • Toolsets (*.toolset.yaml) bundle named tool collections.
  • MCP servers (mcp-servers.yaml) plug in any stdio‑transport MCP server.
  • shell-mcp is a companion binary that turns a JSON manifest into a fast local tool surface — git, gh, anything you'd put behind a shell command.

Curings — multi-stage workflows

A *.curing.yaml binds one agent to one input queue. Compose pipelines by writing one curing's output into the next curing's input queue. Runs under plain leather serve; no tannery required.

  • Queues — per‑curing FIFO with bounded depth, backpressure, configurable concurrency, exponential‑backoff retry, and a dead‑letter queue for items that exhaust their retry budget. Inspectable via /queues and /queues/{name}.
  • CLI ingest — leather ingest path/to/file --kind <hide-kind> --curing <name> drops a hide directly onto a curing queue, no HTTP needed.
  • Process lock — non‑blocking <state-dir>/leather.lock; a second leather serve against the same state directory exits with code 2 and a clear stderr message.

HTTP poll workers

*.worker.yaml files under --worker-dir run background HTTP pollers that push results into named queues — RSS feeds, status pages, JSON APIs — with retry/backoff and the same dead-letter routing as curings.

Tannery — HTTP intake, hides, and artifacts

Add a tannery.yaml next to your config and leather serve also stands up:

  • Intake (POST /intake) and webhooks (POST /webhooks/{name}) — HMAC‑validated, per‑route body‑size caps, source/event matching dispatches into the right curing queue.
  • Hides — raw inputs (PR threads, API responses, logs, files) stored content‑addressed under hide_dir. Agents only ever see a bounded cut through a paged HideBuffer, so multi‑megabyte inputs can't blow the context window. Browseable via /hides and /hides/{id}.
  • Artifacts — promoted outputs stored content‑addressed under artifact_dir with lineage (which curing, which input hide(s), which agent, when). Queryable via /artifacts and /artifacts/{id}.

Replay, snapshots, and run history

  • --persist-runs writes every turn to JSONL with rotation
  • --replay and --replay-live reconstruct past sessions deterministically
  • /snapshot captures live state; /replay/control drives playback when the API is enabled

Browser DevTools UI

With --api, leather serve exposes a single-page UI at /ui/devtools.html: session timeline, prompt/tool event inspector, curing flow diagram, queue and worker status, and live SSE updates. No build step, no JS dependencies — served straight from the binary.

HTTP API

Loopback-bound by default (127.0.0.1:7749):

  • Runtime: /healthz, /status, /metrics, /config, /history
  • Scheduler & queues: /jobs, /jobs/{id}, /queues, /queues/{name}, /workers
  • Cache: /cache/stats
  • Tannery (when enabled): /intake, /webhooks/*, /hides, /hides/{id}, /artifacts, /artifacts/{id}, /curings
  • Replay: /snapshot, /replay/control
  • DevTools: /api/devtools/snapshot, /api/devtools/inspect/..., /api/devtools/trace/...

Notifications

Finished agent runs can be delivered to messaging sinks via per-agent output routes. Built-in Telegram and Signal backends ship in internal/notify; curing outputs can additionally land in queues or be promoted to artifacts.

Build your own

1. Write an agent

---
name: summarizer
---
You are a concise planning assistant. Output bullet points only.

That's a complete *.agent.md file. Front matter declares identity, the body is the system prompt.

2. Give it a schedule (optional)

agent: summarizer
schedule: "0 9 * * *"
model: llama3
prompt: Summarize the three most important things to do today.

*.lifecycle.yaml files sit next to agents and carry the when and how.

3. Run it

leather validate                                  # check everything parses
leather run ~/.leather/agents/summarizer.agent.md # run once
leather serve --pretty --stats                    # run on schedule
leather chat --model llama3                       # talk to the model interactively

4. Add a workflow (when one agent isn't enough)

Two agents passing a hide between them, dispatched by a webhook:

# tannery.yaml
hide_dir: ./.tannery/hides
artifact_dir: ./.tannery/artifacts
curing_dir: ./curings
webhooks:
  - name: github
    path: /webhooks/github
    source: github
    secret: "{{env:GITHUB_WEBHOOK_SECRET}}"
routes:
  - name: pr-review
    match:
      source: github
      event_type: pull_request
    hide_kind: github.pull_request
    curing: triage
    queue: triage-in

Each curing binds one agent to one queue. Chain them by writing the output of the first into the input queue of the second:

# curings/triage.curing.yaml — first stage
name: triage
agent: triage      # classifies the PR, tags it
hide_types: [github.pull_request]
queue: triage-in
output:
  queue: review-in # hand off to the reviewer
# curings/review.curing.yaml — second stage
name: review
agent: reviewer    # reads the diff in cuts, writes the verdict
hide_types: [github.pull_request]
queue: review-in
output:
  artifact: true

See examples/06-multi-agent-curing for a working two-curing chain and examples/10-ci-gate for a webhook-driven fan-out.

leather serve --config tannery/config.yaml
# any POST to /webhooks/github with a valid HMAC now enqueues a curing run

You've just built a two-stage agent pipeline triggered by a GitHub webhook, running in a single local process.


The vocabulary

leather uses a deliberate metaphor borrowed from leatherworking. Sixty seconds here makes the rest of the docs read smoothly:

Leather    the CLI/runtime/binary
Tanning    your local working area — configs, agents, curings, tools (a folder)
Tannery    the long-running workspace service composed from queue+worker+scheduler+session
Hide       raw input material — a PR thread, an API response, a log
HideBuffer in-memory paged view of one hide
Cut        the bounded slice an agent actually sees in its context window
Curing     a named N-agent workflow that transforms hides into artifacts
Operation  one agent working on one or more cuts in a single turn
Artifact   stabilized output with lineage (which curing, which hide, when)
Intake     how hides get created (webhook, HTTP poll, CLI ingest, file)

Full reference: docs/GLOSSARY.md.


Install

From source:

git clone https://github.com/tgpski/leather
cd leather
make build && make build-shell-mcp

With go install:

go install github.com/tgpski/leather/cmd/leather@latest
go install github.com/tgpski/leather/cmd/shell-mcp@latest

Verify the install — no LLM endpoint required:

leather --version    # prints version
make example-01      # runs a mock-LLM example end-to-end

Commands

CommandPurpose
leather initScaffold ~/.leather with .env, config.yaml, an example agent, and a Makefile.
leather doctorPrint every effective config value with source attribution; redacts secrets.
leather serveRun scheduler, queue workers, and (when enabled) HTTP API, tannery, or replay.
leather runExecute one agent definition once and exit.
leather chatInteractive chat session with token‑budget management.
leather ingestCreate a hide from a file or stdin and (optionally) enqueue a curing.
leather workflowRun bounded one-shot tannery workflows to queue quiescence.
leather validateValidate config, agents, lifecycles, skills, workers, and MCP servers.
leather test-agentRun an agent against MockLLM and print the transcript.
leather statusPrint scheduler state and current token‑budget settings.
leather snapshotSave or restore a point-in-time tar.gz archive of runtime state.
leather dlqInspect and requeue outbound dead-letter queue items.
leather attachJoin a running serve instance and stream pretty-printed runtime events.
leather replayReplay a snapshot or live session.
leather version / leather helpThe obvious.

Configuration

config.Load seeds defaults from built‑ins and LEATHER_* env vars, overlays config.yaml, then applies explicitly‑set CLI flags. In order of precedence:

  1. Explicit flag
  2. YAML config
  3. Environment variable
  4. Built‑in default

Every flag has a matching env var: --flag-name → LEATHER_FLAG_NAME.

FlagEnv varDefaultNotes
--configLEATHER_CONFIG~/.leather/config.yamlConfig file path.
--agent-dirLEATHER_AGENT_DIR~/.leather/agentsAgent and lifecycle directory.
--modelLEATHER_MODELemptyGlobal default model name.
--temperatureLEATHER_TEMPERATURE0.7Global default sampling temperature.
--log-levelLEATHER_LOG_LEVELinfodebug, info, warn, error.
--log-formatLEATHER_LOG_FORMATtexttext or json.
--max-tokensLEATHER_MAX_TOKENS8192Default max context window.
--completion-reserveLEATHER_COMPLETION_RESERVE1024Tokens reserved for completion.
--summarize-thresholdLEATHER_SUMMARIZE_THRESHOLD0.85Summarization trigger ratio.
--llm-endpointLEATHER_LLM_ENDPOINThttp://localhost:11434OpenAI‑compatible base URL.
--llm-api-keyLEATHER_LLM_API_KEYemptyBearer token for cloud OpenAI‑compatible endpoints. Empty = no auth.
--llm-timeoutLEATHER_LLM_TIMEOUT60sRequest timeout.
--scheduler-tickLEATHER_SCHEDULER_TICK1mScheduler wake interval.
--max-concurrent-jobsLEATHER_MAX_CONCURRENT_JOBS4Scheduler concurrency cap.
--run-durationLEATHER_RUN_DURATION0Serve exits after this duration; 0 means unlimited.
--max-jobsLEATHER_MAX_JOBS0Serve exits after this many completed jobs; 0 means unlimited.
--state-dirLEATHER_STATE_DIR~/.leather/.stateScheduler state root.
--apiLEATHER_APIfalseEnable serve HTTP API.
--api-addrLEATHER_API_ADDR127.0.0.1:7749HTTP API bind address. Loopback recommended; see security note below.
--log-fileLEATHER_LOG_FILEemptyTee structured logs to file, or file‑only in pretty mode.
--prettyLEATHER_PRETTYfalseHuman‑readable console rendering.
--pretty-modeLEATHER_PRETTY_MODEallmessages or all.
--statsLEATHER_STATSfalsePrint token stats and summaries.
--tokens-per-turnLEATHER_TOKENS_PER_TURNfalsePrint per‑turn token usage in pretty mode.
--persist-runsLEATHER_PERSIST_RUNSfalsePersist JSONL run history.
--run-history-dirLEATHER_RUN_HISTORY_DIRemptyDefaults to <state-dir>/runs when persistence is enabled.
--run-max-bytesLEATHER_RUN_MAX_BYTES10485760Rotate run logs at this size.
--replayLEATHER_REPLAYemptySnapshot replay file.
--replay-liveLEATHER_REPLAY_LIVEemptyLive replay directory.
--replay-speedLEATHER_REPLAY_SPEED1.0Replay speed multiplier.
--tool-dirLEATHER_TOOL_DIRemptyDirectory containing *.skill.yaml and *.toolset.yaml.
--default-toolsetsLEATHER_DEFAULT_TOOLSETSemptyComma‑separated toolsets applied to every agent.
--max-tool-roundsLEATHER_MAX_TOOL_ROUNDS5Default tool‑call round cap.
--worker-dirLEATHER_WORKER_DIRemptyDirectory containing *.worker.yaml.
--cache-dirLEATHER_CACHE_DIRemptyDefaults to <state-dir>/cache in serve mode.
--mcp-servers-fileLEATHER_MCP_SERVERS_FILEemptyrun, serve, and validate fall back to ~/.leather/mcp-servers.yaml.
--loopLEATHER_LOOP1Repeat leather run this many times.

Cloud LLM endpoints

leather speaks the OpenAI Chat Completions API, so any cloud or self‑hosted endpoint that implements the same spec works without a Go recompile — only llm_endpoint, model, and an API key change.

Provide the bearer token in whichever form fits your deployment:

# Inline (good for one‑offs)
leather run --agent hello \
  --llm-endpoint https://api.openai.com \
  --model gpt-4o-mini \
  --llm-api-key "sk-..."

# Environment variable
export LEATHER_LLM_API_KEY="sk-..."
leather serve --llm-endpoint https://api.openai.com --model gpt-4o-mini

For long‑running servers the recommended form is the Unix pass store, with an env var as fallback. In config.yaml:

llm_endpoint: https://api.openai.com
model: gpt-4o-mini
llm_api_key:
  pass: openai/api-key       # `pass show openai/api-key`
  env:  OPENAI_API_KEY       # fallback when pass is empty or unavailable

Go deeper

Ver o original no GitHub

Bom para

Relacionados