Open source · MIT · TypeScript and Python
Let agents use tools.
Stay in control of what they do.
Matimo is the governance layer for AI agent tools. Every call is risk-checked, every risky one is approved by a human, and every result lands on a tamper-evident log.
Building with agents? Serve tools to Claude DesktopResponsible for what agents can do? Require approval for risky calls
$ npm install matimo- Governed by default. DELETE and shell tools ask a human before they run. When your host passes agent context, an agent cannot approve its own tool.
- A log that shows edits. Each entry is linked to the one before it, so an edit or removal is detected. It does not prevent one.
- Self-extending. Meta-tools let agents draft new capabilities mid-conversation, approved by someone else.
- Runs in your process. MIT licensed. Same YAML, policy rules and meta-tools in TypeScript and Python. Composio is TypeScript only.
Watch
Agent-written tool to audit log in 60 seconds
A short walkthrough built from real recorded runs of npm matimo 0.3.0 and PyPI matimo 0.2.0. Recorded against published versions; some behavior may differ in the next release. The narration is synthetic.
Read the transcript
Your agent just wrote a tool. Did anyone read it first? In TypeScript, Matimo gives your agent fifteen meta-tools. It can search tools, read skills, and write a new tool itself. It starts as a draft. Call it now, and it does not exist. Approve it, and it runs. Risky calls ask first too. HTTP deletes and shell commands wait for approval. One command serves every tool, yours and the built-ins, to MCP clients. Executions are chained into an audit log. Edit one value and verification finds the line. Open source, MIT. npm install matimo. Your agent's next tool waits for you.
The core idea
Your AI agent asks before it does anything risky
Matimo sits between your agent and its tools. Safe actions run right away, risky ones wait for a person to say yes, and everything is written to a log you can check later.
- Every action is rated. Before a tool runs, Matimo rates it low, medium, high or critical using rules you can read.
- Risky ones wait for a human. Deleting data or running a shell command pauses until a person approves. If nobody answers, it is refused.
- A log that shows edits. Each entry is linked to the one before it, so an edit or removal is detected. It does not prevent one.
Governance first, then everything else
Policy engine
Every tool call, built-in, third-party or agent-created, is risk-classified (low to critical) and checked against deterministic rules before it runs.
Human-in-the-loop
Calls at or above your risk threshold pause for approval. HTTP DELETE and shell tools ask before every call, with signed approval manifests.
Self-extending agents
15 meta-tools let an agent write a new YAML tool, validate it, get it approved and hot-reload it mid-conversation, under the same governance.
One definition, every framework
Define a tool once in YAML. Run it from TypeScript, Python, LangChain, CrewAI, Agno or any MCP client with the same policy enforcement.
Run a tool. Let an agent write one.
The same call in both SDKs. An agent-created tool starts as a draft and needs approval before it runs.
import asyncio
from matimo import Matimo
async def main():
matimo = await Matimo.init(auto_discover=True)
result = await matimo.execute('slack_send_channel_message', {
'channel': '#general',
'text': 'Hello Matimo!',
})
print(result)
asyncio.run(main())await matimo.execute('matimo_create_tool', {
'name': 'fetch-weather',
'yaml_content': """
name: fetch-weather
version: "1.0.0"
description: Get current weather for a city
execution:
type: http
method: GET
url: https://wttr.in/{city}?format=j1
parameters:
city:
type: string
required: true
""",
})
# The tool is now a draft. A human reviews it:
# matimo review approve fetch-weatherimport { MatimoInstance } from 'matimo';
const matimo = await MatimoInstance.init({ autoDiscover: true });
const result = await matimo.execute('slack_send_channel_message', {
channel: '#general',
text: 'Hello Matimo!',
});await matimo.execute('matimo_create_tool', {
name: 'fetch-weather',
yaml_content: `
name: fetch-weather
version: "1.0.0"
description: Get current weather for a city
execution:
type: http
method: GET
url: https://wttr.in/{city}?format=j1
parameters:
city:
type: string
required: true
`,
});
// The tool is now a draft. A human reviews it:
// npx matimo review approve fetch-weatherTry it: approve or deny a risky call
A replay of a real run of the Python SDK. Press Run, then choose what the human reviewer does. Nothing is executed in your browser.
from matimo import Matimo, MatimoError, JsonlFileSink, verify_audit_log
async def on_approval(request):
return await ask_a_human(request) # you decide
matimo = await Matimo.init(
"./tools",
on_approval=on_approval,
audit_sink=JsonlFileSink("./audit.jsonl"),
)
await matimo.execute("add_numbers", {"a": 2, "b": 3})
await matimo.execute("clear_cache", {"path": "./build"})
verify_audit_log("./audit.jsonl")Press Run to start.
Want the real thing? Run it locally in five minutes.
How Matimo is different
Most agent tooling stops at "here are functions to call". Matimo adds the checks before a call and the record after it, and keeps both in your hands.
| A plain tool library | A hosted tool gateway | Matimo OSS | |
|---|---|---|---|
| Where it runs | In your process | On the vendor's servers | In your process (TypeScript or Python) |
| Checks before a call | You write them | The vendor's rules | Risk class, policy file and human approval, built in |
| Agent creates its own tool | Not covered | Varies | Starts as a draft; needs approval before it runs |
| Record of what ran | Your own logging | The vendor's logs | A hash-chained file you hold, with a verifier that shows edits |
| Tool definition | Code per framework | The vendor's catalog | One YAML for every framework, plus your own tools |
| Third-party catalogs | Not covered | Their own | Wrap one, such as Composio, under the same policy |
These are general categories, not named products. Why Matimo also lists what Matimo does not do, including compliance certifications, which it has none of.
Build your own tools and MCP server
Enterprises rarely need only public APIs. Matimo is built for your internal ones: define the tool, set the rules, expose it over MCP, and keep the evidence.
1Write a tool in YAML
Describe an internal API or command once: parameters, URL, headers. No SDK code and no per-framework wrapper.
2Set your policy
Keep your rules in a policy.yaml under version control. The policy reference lists the fields it supports.
3Serve it over MCP
Point the MCP server at your tool directory. Claude Desktop, Cursor and any MCP client see only what you expose.
4Approve and audit
Route risky calls to your reviewers and keep the audit log where your security team can verify it.
# tools/crm_lookup_customer/definition.yaml
name: crm_lookup_customer
version: "1.0.0"
description: Look up a customer in the internal CRM
parameters:
customer_id:
type: string
description: The customer ID
required: true
execution:
type: http
method: GET
url: https://crm.internal.example.com/api/customers/{customer_id}
headers:
Authorization: Bearer {CRM_API_TOKEN}
# policy.yaml (fields are listed in the policy reference)
allowedDomains:
- crm.internal.example.com
allowedHttpMethods:
- GET
- POST# stdio for Claude Desktop or Cursor, with your own tools
npx matimo mcp --tool-paths ./tools
# a shared server with TLS and Vault-backed secrets
npx matimo mcp --transport http \
--cert cert.pem --key key.pem \
--secrets vault --tool-paths ./toolsWhat stays under your control
- Private tool directories, or your own @yourco/* provider package
- Allow and deny lists for what the MCP server exposes
- Bearer token and TLS for the HTTP transport
- Secrets from environment, .env, Vault or AWS Secrets Manager
- Credentials injected at call time through {NAME} placeholders
- An audit file you own, with no vendor in the call path
Package your own tools →MCP server guide →Policy reference →
Ready-made tools, and room for your own
129 provider tools in 10 packages, plus 449 governed Composio tools in TypeScript. Add your own in a YAML file.
- Slack
- GitHub
- Gmail
- Microsoft
- Notion
- PostgreSQL
- HubSpot
- Mailchimp
- Twilio
- Bruno
- Your own tools
Works everywhere
Deploy to any framework or agent runtime without rewriting a tool.
LangChain
Convert tools to StructuredTool instantly. Works with ReAct, function-calling agents and any LangChain executor.
CrewAI
Convert to BaseTool with async support. Multi-agent crews and hierarchical workflows use the same governed tools.
Claude Desktop and MCP
Run Matimo as an MCP server. Claude Desktop, Cursor and any MCP client see all your tools. One command: npx matimo mcp.
Custom agents
Native SDK for your own agent loop. Factory pattern, decorator pattern or direct calls, whichever fits.
CLI
List, search, install and review tools from the terminal, in both SDKs.
Any model provider
OpenAI, Anthropic, Google, Ollama. Matimo sits on the tool side, so it does not care which model calls it.
Complete feature set
Everything needed to run agent tools in production.
1Core SDK
YAML-first tools
Define a tool once and run it from TypeScript, Python and any framework.
Hot-reload registry
Add or change tools at runtime without restarting your application.
Schema validation
Zod in TypeScript and Pydantic in Python for tool definitions and types.
Dual SDKs
TypeScript (Node 22.19+) and Python (3.11+) share the YAML format, policy rules and meta-tools. Composio is TypeScript only.
2129 ready-made tools
Slack and Gmail
Messages, channels and threads. Send, read and draft email.
GitHub
Issues, pull requests, repositories, code search and workflows.
Notion and HubSpot
Pages and databases. Contacts, deals and companies.
PostgreSQL
Parameterized SQL execution behind the policy engine.
Mailchimp and Twilio
Campaigns and audiences. SMS and MMS.
Microsoft and Bruno
Microsoft 365 tools and API-collection testing tools.
3Policy engine and governance
Risk classification
Every call is rated low, medium, high or critical with configurable policies.
Approval gates
Human-in-the-loop approval for sensitive operations, with signed manifests.
Audit trail
A hash-chained event log with secrets redacted. An edit or removed line is detected; it is not prevented.
Content validation
Pattern-based rules on agent-created tools before they can be approved.
Integrity tracking
Hash-based tamper detection so approved tools cannot change silently.
Approval expiry
Approvals carry a time limit and lapse on their own.
4Skills and self-extension
Skill search
TF-IDF keyword-relevance discovery of domain knowledge.
Skill library
Markdown SKILL.md files with YAML frontmatter, loaded only when relevant.
15 meta-tools
Create, validate, approve and reload tools and skills at runtime.
Agent self-extension
An agent can draft a tool. When your host passes agent context, the agent cannot approve its own tool.
5Integrations
LangChain
Convert tools to StructuredTool and add Matimo to existing agents.
CrewAI and Agno
Convert to framework tools with the same policy enforcement.
MCP server
stdio and HTTP transports for Claude Desktop, Cursor and other clients.
Composio catalog
449 governed tools across 14 toolkits (TypeScript, @matimo/composio).
6Auth and secrets
OAuth2 support
Provider-agnostic OAuth2 with token handling for Google, GitHub, Slack and others.
Placeholder credentials
Credentials are injected at call time through {NAME} placeholders, not stored in tool files.
Redacted logging
Secrets are redacted in audit events and error output.
Why teams choose Matimo
Dual SDKs
TypeScript and Python share the YAML format, policy rules and meta-tools. Composio is TypeScript only.
No tool duplication
Define once in YAML and use it from every framework.
Framework freedom
LangChain, CrewAI, MCP or your own loop, with the same tools.
Faster start
Ready-made Slack, GitHub, Gmail, Notion and more from day one.
Type safe
TypeScript types and Python hints, with Zod and Pydantic validation.
Community tools
A growing set of @matimo/* provider packages.
Agent self-extension
Agents build new tools at runtime, checked by policy.
Safe by default
Risky tools ask first. When your host passes agent context, an agent cannot approve its own creations.
Open source
MIT licensed, with about 4,700 tests across both SDKs (2,825 TypeScript run, 1,886 Python collected, counted 2026-10-29).
Four integration patterns
Pick what fits. Each pattern is shown in both SDKs.
1Factory pattern
Load tools and execute by name. Good for scripts, CLIs and quick prototypes.
matimo = await Matimo.init(auto_discover=True)
result = await matimo.execute('tool-name', params)const matimo = await MatimoInstance.init({ autoDiscover: true });
await matimo.execute('tool-name', params);2Decorator pattern
Class-based approach. The @tool decorator executes the named tool for you.
class Agent:
@tool('tool-name')
async def my_method(self, param):
pass # executed through Matimoclass Agent {
@tool('tool-name')
async myMethod(param: string) {
// executed through Matimo
}
}3Framework integration
Convert Matimo tools to LangChain or CrewAI tools automatically.
from matimo import convert_tools_to_langchain
tools = convert_tools_to_langchain(matimo.list_tools(), matimo)import { convertToolsToLangChain } from '@matimo/core';
const tools = await convertToolsToLangChain(matimo.listTools(), matimo);4MCP server
Run Matimo as a standalone MCP server for Claude Desktop, Cursor and any MCP client.
from matimo.mcp.server import MCPServer, MCPServerOptions
server = MCPServer(matimo, MCPServerOptions(transport="stdio"))
await server.start()# stdio (Claude Desktop)
npx matimo mcp
# HTTP (remote agents)
npx matimo mcp --transport httpDeveloper CLI
Environment setup, validation and approval workflows from the terminal. Run it with npx matimo or, in Python, matimo.
Environment diagnostics
npx matimo doctorChecks versions, installed @matimo/* packages, missing environment variables and YAML validity.
Approval workflows
npx matimo review listLists tools waiting for approval or in quarantine. Approve or reject from the terminal.
MCP setup
npx matimo mcp setupGenerates and writes the Claude Desktop configuration in one command.
Quick start resources
Quick start
A five-minute walkthrough with TypeScript and Python side by side.
Create your first tool
Build HTTP and command tools in YAML with validation.
API reference
SDK, policy, approval, meta-tools, errors and logging.
Skills system
Domain knowledge for agents, with TF-IDF search.
Architecture
How the registry, executors and policy engine fit together.
Examples
Runnable LangChain, CrewAI, MCP and native examples.
Discord community
Ask maintainers, share tools and follow releases.
Production ready
Tested
About 4,700 tests across both SDKs. A pre-push hook runs both test suites. TypeScript coverage floors are 95% lines, 97% functions and 87% branches; Python core must stay at 95%.
Security controls
Secret isolation, command-injection prevention, integrity tracking and a fail-closed policy engine. No compliance certifications are held.
153 native tools
129 provider tools in 10 packages plus 24 core tools (15 of them meta-tools), and 449 more through Composio (TypeScript only).
Governance built in
Risk tiers, quarantine, approval manifests and an audit trail you can use in a compliance review.
One definition
The same YAML tool definition is used by both SDKs.
Open source
MIT licensed. Releases on npm (0.4.0) and PyPI (0.2.0).
Works with the frameworks you already use
- LangChain
- CrewAI
- Agno
- MCP
- Claude Desktop
- Cursor
For AI agents
Machine-readable docs for agents
Matimo is designed for agent-driven use under human oversight. Everything below is plain text, no JavaScript needed.
llms.txt
What Matimo is, when to use it, how to install it, and where it stops.
llms-full.txt
The core documentation in one file, ready to load into context.
AGENTS.md
Setup, test and commit conventions for coding agents working in the repo.
# TypeScript: core plus the CLI
npm install matimo
# TypeScript: core only
npm install @matimo/core
# Python
pip install matimo
# Serve tools to MCP clients
npx matimo mcp --tool-paths ./toolsReady to govern your agents' tools?
Install it, run your first tool and see the approval gate in about five minutes.
Need a hosted runtime on top?
Matimo Workbench uses Matimo OSS as its tool layer, with a visual builder and managed runtime.
Explore Matimo Workbench