librefang-registry/README.md

LibreFang Registry

Community-maintained content registry for LibreFang -- the open-source Agent Operating System.

This repository is the single source of truth for all installable content definitions. Anyone can submit a PR to add new agents, hands, integrations, skills, or provider models -- no changes to the LibreFang binary required.

Structure

librefang-registry/
├── agents/             # Agent definitions (TOML manifests)
│   ├── hello-world/agent.toml
│   ├── researcher/agent.toml
│   └── ...             (33 agents)
├── hands/              # Hand definitions (TOML + docs)
│   ├── browser/HAND.toml
│   ├── trader/HAND.toml
│   └── ...             (14 hands)
├── integrations/       # MCP server integration templates
│   ├── github.toml
│   ├── slack.toml
│   └── ...             (25 integrations)
├── skills/             # Reusable skill definitions
│   ├── custom-skill-prompt/skill.toml
│   └── custom-skill-python/
├── providers/          # LLM provider & model metadata
│   ├── anthropic.toml
│   ├── openai.toml
│   └── ...             (46 providers, 190+ models)
├── plugins/            # Plugin packages (10 plugins)
├── aliases.toml        # Global model alias mappings
├── schema.toml         # Provider/model schema reference
├── scripts/
│   └── validate.py     # Validation script
├── CONTRIBUTING.md
└── LICENSE             # MIT

Content Types

Agents

Agent definitions in agents/<name>/agent.toml describe autonomous agents with their model config, tools, capabilities, and routing aliases.

name = "hello-world"
description = "A friendly greeting agent"
module = "builtin:chat"

[model]
provider = "default"
model = "default"
system_prompt = "You are a helpful assistant."

[capabilities]
tools = ["web_search", "file_read"]

Hands

Hands in hands/<name>/HAND.toml are higher-level application bundles -- the user-facing "apps" in LibreFang. Each hand bundles an agent config, tools, settings, dashboard metrics, and dependency requirements.

id = "browser"
name = "Browser Hand"
category = "productivity"
tools = ["browser_navigate", "browser_click", "browser_type"]

[agent]
name = "browser-hand"
module = "builtin:chat"
system_prompt = "You are an autonomous web browser agent..."

[[settings]]
key = "headless"
setting_type = "toggle"
default = "true"

Integrations

Integration templates in integrations/<name>.toml define MCP server connections (GitHub, Slack, databases, etc.) with transport config, required env vars, and setup instructions.

id = "github"
name = "GitHub"
category = "devtools"

[transport]
type = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

[[required_env]]
name = "GITHUB_PERSONAL_ACCESS_TOKEN"
is_secret = true

Skills

Skills in skills/<name>/skill.toml are reusable prompt templates or Python scripts that agents can invoke.

[skill]
name = "meeting-agenda"
description = "Generate a structured meeting agenda"

[runtime]
type = "promptonly"

[prompt]
template = "Create a meeting agenda for: {{topic}}"

Providers

Provider files in providers/<name>.toml define LLM providers and their models with pricing, context windows, and capability flags. See schema.toml for the full field reference.

How LibreFang Uses This Registry

LibreFang ships with built-in content compiled into the binary. This repository serves as the upstream source for updates and community contributions.

# Update all registry content
librefang catalog update

# Install a specific hand
librefang hand install browser

# Install a specific integration
librefang integration install github

Custom Local Content

You can also create custom content locally without submitting a PR:

# Create a custom agent
mkdir -p ~/.librefang/agents/my-agent
# Edit ~/.librefang/agents/my-agent/agent.toml

# Add custom models to your config
# ~/.librefang/model_catalog.toml

Validation

python scripts/validate.py

This validates all provider TOML files for correctness: required fields, valid tiers, non-negative costs, no duplicate IDs.

How to Contribute

1. Fork this repository
2. Add or edit content in the appropriate directory
3. Run validation: python scripts/validate.py
4. Submit a Pull Request

See CONTRIBUTING.md for detailed instructions for each content type.

Current Stats

Type	Count
Agents	33
Hands	14
Integrations	25
Skills	2
Plugins	10
Providers	46
Models	220+
Aliases	80+

License

MIT License. See LICENSE.