2026-07-16 16:11 UTCIn-site rewrite3 min readUpdated: 2026-07-16 16:17 UTC

Show HN: Ratel, give agents unlimited tools and skills without context bloat

Ratel is a context engineering layer for AI agents that indexes tools and skills and injects only those relevant to each turn, reducing token usage by up to 80% and improving accuracy, without requiring a vector database.

SourceHacker News AIAuthor: jack1689

Uh oh!

There was an error while loading. Please reload this page.

Notifications You must be signed in to change notification settings

Fork 9

Star 188

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

85 Commits

.claude/skills/changelog

.github/workflows

docs

e2e

examples

protocol

scripts

src

.adr-dir

.gitignore

.lycheeignore

AGENTS.md

CLAUDE.md

CODE_OF_CONDUCT.md

CONTRIBUTING.md

Cargo.lock

Cargo.toml

LICENSE-APACHE

LICENSE.md

NOTICE

README.md

RELEASING.md

biome.json

cliff.toml

context7.json

llms.txt

package.json

pnpm-lock.yaml

pnpm-workspace.yaml

rust-toolchain.toml

Repository files navigation

Your AI agent is paying for tools it never uses. Ratel fixes that.

Docs • Skills • Discord

Introduction

The context engineering layer for AI agents. Selects only the tools and skills relevant to each turn, recovering accuracy lost to tool overload and cutting what you pay per call. No vector DB, no infra.

Why

Cost: Every tool schema, every skill, and a growing list of instructions in the system prompt are tokens you pay for on every call. Send them all up front and you pay for them all, every turn.

Accuracy: Models get worse as that context grows. Crowd it with tools, skills, and instructions a turn doesn't need and the model picks the wrong option and drifts off task.

Ratel fixes both: it indexes your tools and skills into a catalog the agent progressively discloses, searching for what each turn needs and injecting only the matching capabilities instead of loading everything up front.

Across local, open-source, and frontier model setups, Ratel cuts token usage and recovers accuracy lost to tool overload, with no vector DB required. Full results: benchmark.ratel.sh

Quickstart

Guides: Quickstart · TypeScript SDK · Python SDK

Examples: Vercel AI SDK · Pydantic AI

Typescript

Install the SDK first:

pnpm add @ratel-ai/sdk

Then create and use your Catalogs:

import { readFile } from "node:fs/promises"; import { SkillCatalog, ToolCatalog, getSkillContentTool, invokeToolTool, searchCapabilitiesTool, } from "@ratel-ai/sdk";

const catalog = new ToolCatalog(); catalog.register({ id: "read_file", name: "read_file", description: "Read a file from local disk.", inputSchema: { type: "object", properties: { path: { type: "string" } } }, outputSchema: { type: "object", properties: { contents: { type: "string" } } }, execute: async ({ path }) => ({ contents: await readFile(path, "utf8") }), });

const skills = new SkillCatalog(); skills.register({ id: "inspect-local-file", name: "inspect-local-file", description: "Inspect a local file before answering questions about it.", tools: ["read_file"], body: "Read the requested file, then ground your answer in its contents.", });

// use the following as tools in your agent framework const search = searchCapabilitiesTool(catalog, skills); const invoke = invokeToolTool(catalog); const loadSkill = getSkillContentTool(skills);

Python

Install the SDK first:

pip install ratel-ai

Then create and use your Catalogs:

from ratel_ai import ( ExecutableTool, Skill, SkillCatalog, ToolCatalog, get_skill_content_tool, invoke_tool_tool, search_capabilities_tool, )

catalog = ToolCatalog() catalog.register(ExecutableTool( id="read_file", name="read_file", description="Read a file from local disk.", input_schema={"properties": {"path": {"type": "string"}}}, execute=lambda args: {"contents": open(args["path"]).read()}, ))

skills = SkillCatalog() skills.register(Skill( id="inspect-local-file", name="inspect-local-file", description="Inspect a local file before answering questions about it.", tools=["read_file"], body="Read the requested file, then ground your answer in its contents.", ))

use the following as tools in your agent framework

search = search_capabilities_tool(catalog, skills) invoke = invoke_tool_tool(catalog) load_skill = get_skill_content_tool(skills)

How it works

When your agent needs to act, it calls search_capabilities. Ratel searches separate tool and skill indexes and returns focused results from each. Tools can be invoked by id; skill instructions stay out of context until the agent loads a relevant playbook with get_skill_content.

The indexes use BM25 by default, the same algorithm behind most search engines, applied to schema-aware tool metadata and skill names, descriptions, and tags. Retrieval is fast and deterministic. Semantic and hybrid ranking are opt-in per catalog or per call, running a local embedding model in the same process.

Full docs

Related projects

Related open-source projects extend and validate this repository:

Project Repo What it is

ratel-local ratel-ai/ratel-mcp The local distribution for your Coding Agents: Ratel in front of your MCP setup.

ratel-bench ratel-ai/ratel-bench The benchmark harness behind benchmark.ratel.sh.

Repo layout

src/ ├── core/ # ratel-ai-core — Rust BM25 engine ├── sdk/ts/ # @ratel-ai/sdk — TypeScript SDK (NAPI-bound) ├── sdk/python/ # ratel-ai — Python SDK (PyO3-bound) └── telemetry/ # OTel conventions + helper packages protocol/ # catalog-source wire contract examples/ # End-to-end SDK examples docs/ ├── adr/ # Architecture decision records └── assets/ # Images and other static assets

Build & test

Prerequisites: Rust stable, Node 24+, pnpm 10.28+. Python SDK: Python 3.9+ and uv.

cargo build --workspace && cargo test --workspace # Rust pnpm install && pnpm -r build && pnpm -r test # TypeScript

Python: see src/sdk/python/README.md

Contributing

CONTRIBUTING.md

AGENTS.md — for coding agents working in this repo

License

The ratel-ai-core engine is licensed under Apache-2.0 — an explicit patent grant for the engine others embed. Everything else (SDKs, telemetry helpers, examples) is MIT. See ADR-0009 for the rationale.

About

Context engineering for AI agents. ~80% fewer tokens. Fix tool overload. Skills and memory with in-process BM25 and semantic retrieval. Progressive Disclosure. No vector DB.

www.ratel.sh/

Topics

skills

memory

optimization

mcp

context

accuracy

agents

harness

rag

llm

tool-selection

tool-calling

llm-routing

mcp-server

token-optimization

claude-skills

Resources

Readme

License

MIT, Apache-2.0 licenses found

MIT

LICENSE.md

Apache-2.0

LICENSE-APACHE

Code of conduct

Contributing

Uh oh!

There was an error while loading. Please reload this page.

Activity

Custom properties

Stars

188 stars

Watchers

2 watching

Forks

9 forks

Report repository

Releases 40

sdk-py-v0.4.2

Latest

Jul 11, 2026

+ 39 releases

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Rust 31.0%

TypeScript 29.0%

Python 28.5%

JavaScript 8.9%

Shell 2.6%