leather

package module
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 5, 2026 License: GPL-3.0 Imports: 0 Imported by: 0

README

leather

releases | changelog | pkg.go.dev | leather.sh | pate.sh

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.

cat > summarizer.agent.md <<'EOF'
---
name: summarizer
---
You are a concise planning assistant. Output bullet points only.
EOF

leather validate --agent-dir .
leather run summarizer.agent.md

See it run

Sixteen demos in examples/, each one make target away.

Example 02: scheduled agent 
cp examples/env.example examples/.env
$EDITOR examples/.env
make example-02

Animated GIF of a terminal running 'make example-02' to start a scheduled agent, then showing the agent's output in the terminal

Example 06: multi-agent curing + devtools UI 
make example-06

Animated GIF of a terminal running 'make example-06' to start a multi-agent curing
Screenshot of the devtools UI showing a causal chain of queue, agent, and tool events for a two-curing run

Same code path also runs a profiled 100-webhook burst — 500 LLM calls, 965K tokens, five fan-out/fan-in stages — end to end in 190s at 6.5% avg host CPU and no measurable IO pressure. Leather isn't the bottleneck; the model is. Full profile in examples/11-high-volume-ci.

What it does
Agents *.agent.md — Markdown front and a system prompt with 0-N turns and variable support.
Tools Skills, toolsets, MCP server support, and shell-mcp (make build-shell-mcp) for turning shell commands into agent tools.
Curings Bind agents to queues for flexible multi-stage routing.
Queues Filesystem FIFO — configurable depth, backpressure, concurrency, dead-letter routing, and single-use parameterized queues.
Workers Goroutines with hooks into queues.
Tannery Pipelines connecting agents, curings, workers, and artifacts, with fan-in / fan-out routing.
DevTools Stdlib-JS UI with session timeline, event inspector, curing flow diagram, and live SSE.
Notifications Telegram and Signal backends.

Build one

A complete agent:

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

A schedule for it (*.lifecycle.yaml, optional):

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

Run it:

leather validate                                  # check everything parses
leather run ~/.leather/agents/summarizer.agent.md # run once
leather serve --pretty --stats                    # run on schedule

Chaining two agents behind a webhook — one triages, one reviews, an artifact comes out the other end — is the same primitives composed: see the GUIDE.md: two-agent pipeline recipe and examples/06-multi-agent-curing.

Install

From source:

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

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

Model and endpoint

Every command above needs a model and an LLM endpoint from somewhere. All three forms set the same values — flag wins over env var, env var wins over config.yaml:

# flag
leather run agent.md --model llama3 --llm-endpoint http://localhost:11434

# env var
export LEATHER_MODEL=llama3
export LEATHER_LLM_ENDPOINT=http://localhost:11434

# config.yaml
model: llama3
llm_endpoint: http://localhost:11434

leather speaks the OpenAI Chat Completions API, so cloud endpoints work the same way. The bearer token resolves inline value → pass → env var, in that order:

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

# config.yaml + unix pass
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

Documentation

Overview

Package leather is a stdlib-only Go binary that runs declarative agents locally — scheduled jobs, one-shot runs, webhook-driven workflows, tool calling, and auditable outputs — without a Python stack, hosted control plane, or external dependency pile.

This package is intentionally empty. The runtime lives in the leather binary at github.com/TGPSKI/leather/cmd/leather and the shell-manifest MCP companion at github.com/TGPSKI/leather/cmd/shell-mcp. Implementation packages live under internal/ and are not part of the public Go API.

Install 

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

Pre-built binaries

Tagged releases publish linux/darwin × amd64/arm64 tarballs at https://github.com/TGPSKI/leather/releases.

Documentation

See the project README and docs/ tree on GitHub for full usage, the agent definition format, the curing/tannery workflow model, and the HTTP API surface: https://github.com/TGPSKI/leather.

Source Files

View all Source files

Directories

Path Synopsis
cmd
leather command
Command leather is the main entrypoint for the leather agent orchestrator.
 Command leather is the main entrypoint for the leather agent orchestrator.
shell-mcp command
shell-mcp is a stdlib-only MCP stdio server that exposes fast CLI tools as model-callable tools.
 shell-mcp is a stdlib-only MCP stdio server that exposes fast CLI tools as model-callable tools.
internal
agent
Package agent implements loading, parsing, and validation of agent definition files.
 Package agent implements loading, parsing, and validation of agent definition files.
artifact
Package artifact provides a file-backed store for curing output artifacts.
 Package artifact provides a file-backed store for curing output artifacts.
cache
Package cache provides a sha256-keyed, file-backed response cache with per-entry TTL.
 Package cache provides a sha256-keyed, file-backed response cache with per-entry TTL.
cli
Package cli implements leather's command dispatch and serve loop.
 Package cli implements leather's command dispatch and serve loop.
config
Package config loads and merges leather configuration from multiple sources.
 Package config loads and merges leather configuration from multiple sources.
curing
Package curing loads curing workflow definitions and provides a first-match router for mapping intake events to curing workflows.
 Package curing loads curing workflow definitions and provides a first-match router for mapping intake events to curing workflows.
devtools/bus
Package bus provides an in-memory event bus for DevTools consumers.
 Package bus provides an in-memory event bus for DevTools consumers.
devtools/causality
Package causality derives and traverses event lineage for DevTools.
 Package causality derives and traverses event lineage for DevTools.
devtools/sources
Package sources maps runtime signals to DevTools bus events.
 Package sources maps runtime signals to DevTools bus events.
fileutil
Package fileutil provides small filesystem helpers shared across leather: existence checks and atomic file writes via a temp-file rename.
 Package fileutil provides small filesystem helpers shared across leather: existence checks and atomic file writes via a temp-file rename.
hide
Package hide implements the HideBuffer — an in-process store for large tool outputs.
 Package hide implements the HideBuffer — an in-process store for large tool outputs.
httpx
Package httpx provides shared HTTP response helpers for leather's API handlers.
 Package httpx provides shared HTTP response helpers for leather's API handlers.
ids
Package ids generates the identifier strings used across leather.
 Package ids generates the identifier strings used across leather.
jsonstore
Package jsonstore persists Go values as JSON files on disk.
 Package jsonstore persists Go values as JSON files on disk.
logging
Package logging provides structured logging for leather components.
 Package logging provides structured logging for leather components.
mcp
Package mcp implements an MCP (Model Context Protocol) client over the stdio transport using JSON-RPC 2.0.
 Package mcp implements an MCP (Model Context Protocol) client over the stdio transport using JSON-RPC 2.0.
model
Package model defines the shared domain types for leather.
 Package model defines the shared domain types for leather.
notify
Package notify provides a Notifier interface and concrete backends for delivering agent output to messaging platforms (Telegram, Signal).
 Package notify provides a Notifier interface and concrete backends for delivering agent output to messaging platforms (Telegram, Signal).
queue
Package queue provides a durable, file-backed FIFO queue for QueueItems.
 Package queue provides a durable, file-backed FIFO queue for QueueItems.
runner
Package runner executes a single agent turn, including multi-round tool calling.
 Package runner executes a single agent turn, including multi-round tool calling.
safepath
Package safepath provides root-anchored path joins that reject traversal.
 Package safepath provides root-anchored path joins that reject traversal.
scheduler
Package scheduler implements cron expression parsing and schedule computation.
 Package scheduler implements cron expression parsing and schedule computation.
schema
Package schema provides lightweight schema validation for leather definition files.
 Package schema provides lightweight schema validation for leather definition files.
secret
Package secret resolves credentials from operator-friendly sources without ever passing the resolved value through structured logs.
 Package secret resolves credentials from operator-friendly sources without ever passing the resolved value through structured logs.
session
Package session manages the context window for a single agent execution.
 Package session manages the context window for a single agent execution.
tool
Package tool manages the tool registry: loading skill definitions from *.skill.yaml files, validating tool names, and dispatching executions.
 Package tool manages the tool registry: loading skill definitions from *.skill.yaml files, validating tool names, and dispatching executions.
worker
Package worker loads and runs polling workers that push items into named queues.
 Package worker loads and runs polling workers that push items into named queues.
yamlx
Package yamlx is leather's stdlib-only parser for the small, flat subset of YAML used by config files, agent front-matter, and lifecycle definitions.
 Package yamlx is leather's stdlib-only parser for the small, flat subset of YAML used by config files, agent front-matter, and lifecycle definitions.
Package ui embeds the leather DevTools / overview web UI so that `leather serve` can serve it at /ui/* from the binary, with no need for the operator to know where the repository's ui/ directory lives.
 Package ui embeds the leather DevTools / overview web UI so that `leather serve` can serve it at /ui/* from the binary, with no need for the operator to know where the repository's ui/ directory lives.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.