Matimo Documentation

Matimo, Enable AI Agents To Build Themselves

Open-source tool governance for AI agents: every call risk-checked, every risky one approved by a human, every result on a log you can verify

Give your agents 129 production-ready tools to start (plus a governed 449-tool Composio catalog). Then activate 15 meta-tools that let them create, validate, and approve new capabilities at runtime, governed by your policy engine with human approval workflows for critical actions.

Self-extending agents with enterprise-grade control:

Meta-Tools: Agents write new tool definitions in YAML, validate schemas, approve for production, and hot-reload, all mid-conversation
Policy Engine: Classify every action by risk level, block dangerous operations, quarantine draft tools
Human-in-the-Loop (HITL): Critical tools require human approval before execution with configurable timeouts and audit trails
Universal Integration: One YAML definition works across TypeScript, Python, LangChain, CrewAI, Claude MCP, OpenAI

New here? Read Why Matimo OSS and what changed in 0.2.0.

Complete documentation for Matimo 0.4.0 (TypeScript @matimo/core and Python matimo, both 0.4.0).

New in 0.4.0: TypeScript and Python now share one version number. HTTP MCP servers bind 127.0.0.1 by default and the Python one needs a bearer token (set MATIMO_MCP_TOKEN), execute takes args and an opt-in shell that always asks a human, network tools refuse hostnames that resolve to internal addresses, and MATIMO_FILE_ROOTS can confine the file tools. Read the release notes before upgrading.

Since 0.2.0, secure by default. HTTP DELETE and command tools ask a human before every call, each instance has its own approval callback (onApproval), MCP servers ask the client’s user through elicitation, every call emits events you can keep in a tamper-evident audit log, and both SDKs enforce the same rules. Upgrading? Read the migration guide.

Choose Your SDK

TypeScript / Node.js

Node.js 22.19+, npm/pnpm
ESM, full type support
Enforced coverage floors (95% lines)
Start with TypeScript

Python Stable Release

Python 3.11+, pip/uv
Native asyncio, full type hints (mypy strict)
LangChain, CrewAI, MCP support
Start with Python

Getting Started

TypeScript Getting Started

Quick Start: 5-minute setup
Your First Tool: Create a basic YAML tool
API Reference: SDK fundamentals

Python Getting Started

Quick Start: 5-minute setup with pip install matimo
Your First Tool: Run the built-in calculator step by step (TypeScript and Python)
LangChain Integration: Build ReAct agents
CrewAI Integration: Multi-agent orchestration
Agno Integration: Governed Agno agents, teams and workflows
API Reference: Python SDK documentation

Installation & Requirements

Installation: Detailed setup for both SDKs
- TypeScript (Node.js 22.19+) and Python (3.11+) requirements
- From npm/pip (recommended) or from source
- Troubleshooting & environment setup
- Provider authentication via OAuth2

Reference (By Topic)

Core Concepts (Start Here)

Architecture Overview: Understand how Matimo works
- High-level system design
- Three integration patterns (Factory, Decorator, Framework)
- Framework compatibility (LangChain, CrewAI, MCP, custom)
- Data flow and execution model
SDK Patterns: TypeScript & Python examples
- Factory pattern (simplest)
- Decorator pattern (class-based)
- Framework integration patterns
API Reference: Complete SDK reference
- TypeScript MatimoInstance API
- Python Matimo API
- .execute(), .listTools(), .searchTools()
- Error handling & logging
- Complete type definitions
Error Reference: Troubleshooting guide
- Error codes and meanings
- Common scenarios
- Debugging techniques
- Recovery patterns

Tool Development

Tool Specification: Write tools in YAML
- Tool metadata and parameters
- Execution types (http, function, command)
- Authentication and credential placeholders
- Risk, requires_approval and status fields
- Real definitions from the provider packages
Tool Workflow: Checklist for adding a tool to both SDKs
Decorator Guide: @tool methods backed by YAML tools
Adding Tools to Matimo: Publish @matimo/* packages
- 6-step guide for creating providers
- Auto-discovery mechanism
- Publishing to npm
- GitHub provider real example
- CLI tool management
Testing Tools: Unit & integration testing
- Testing patterns with Jest / pytest
- Mocking external services
- TypeScript coverage floors (lines 95%, functions 97%, branches 87%)
- Test fixtures
OAuth Setup: OAuth2 authentication
- OAuth2 flow implementation
- Provider-specific configurations
- Token management
- Security best practices

Policy & Lifecycle (Security)

Policy Engine & Tool Lifecycle: Complete security guide
- PolicyConfig setup and immutability
- Content Validator (9 security rules)
- Risk classification levels
- Tool lifecycle: create → approve → reload → use
- Approval system (interactive, auto-approve, MCP)
- Integrity tracking (SHA-256, HMAC)
- RBAC & access control
- Audit events
Meta-Tools Reference: Built-in tool management tools
- matimo_search_tools / matimo_get_tool / matimo_get_tool_status, Find tools and inspect their definition and status
- matimo_validate_tool: Validate YAML against schema + policy
- matimo_create_tool: Create tools with safety enforcement
- matimo_approve_tool: Promote draft tools with HMAC signing
- matimo_reload_tools: Hot-reload the live registry
- matimo_list_user_tools: Discover tools with metadata
- matimo_create_skill: Create SKILL.md files
- matimo_list_skills: List skills in a directory
- matimo_get_skill: Read a skill’s content by name
- matimo_validate_skill: Validate a skill against the Agent Skills spec
- matimo_search_skills: Rank skills by keyword relevance (TF-IDF)
- matimo_get_skill_sections: Inventory a skill’s sections and token costs
- matimo_get_skill_content: Load only specific sections of a skill
Approval System: Approval handler configuration
- Per-instance onApproval callbacks
- Pre-approved patterns and environment variables
- MCP elicitation
Logging: Logger configuration and formats
MCP Server: Serve Matimo tools to Claude Desktop, Cursor and other MCP clients (setup guides)
Composio: The governed Composio catalog (@matimo/composio)

Advanced Topics

OAuth Architecture: Deep dive into OAuth2
- Protocol flow details
- Provider integrations
- Token lifecycle
- Security considerations
Provider Configuration: Multi-provider setup
- Managing multiple providers
- Configuration patterns
- Environment variables
- Provider-specific settings
Type Definitions: Complete TypeScript types
- Full interface reference
- Parameter and execution types
- Response validation types
Framework Integrations: LangChain (TS + Python), CrewAI, Agno, Vercel AI SDK, Bruno
Skills: SKILL.md knowledge documents and TF-IDF search
Notebooks: Colab notebooks: quickstart, policy engine, meta-tools, skills, MCP server

Project Information

Release Notes: New features, bug fixes, and breaking changes
Roadmap: Upcoming features and long-term vision

For Contributors

Want to contribute? Start here:

Contributing Guidelines: Full contribution workflow
- Setup and development environment
- Code standards and best practices
- TDD (Test-Driven Development) approach
- Commit message format
- PR checklist
Commit Guidelines: Conventional commits standard
- Type, scope, subject format
- Examples for feat, fix, docs, etc.
- Git workflow tips
Development Standards: Code quality requirements
- TypeScript strictness
- Testing coverage (95% floors enforced in CI on TypeScript core and matimo-core)
- ESLint / ruff and Prettier
- JSDoc documentation

Development & Advanced Usage

SDK Patterns: SDK usage patterns and best practices
- Factory pattern usage
- Decorator pattern examples
- LangChain integration patterns
- Error handling strategies
- Performance optimization
Tool Discovery: Finding and using tools
- Auto-discovery from npm packages
- Tool search and filtering
- Registry management
- Loading from directories
Authentication: API keys, OAuth2, and token management
- API key setup
- OAuth2 flows
- Token refresh and storage
- Provider-specific auth patterns
- Security best practices

Troubleshooting

FAQ & Common Issues: Answers to common questions
- Setup problems
- Tool execution issues
- Authentication errors
- Performance tips

Just Getting Started (First 30 minutes)

Quick Start: Install and run your first tool
Your First Tool: Create a basic YAML tool
API Reference: Understand the SDK basics
If stuck → FAQ

Building Tools

Tool Specification: YAML schema reference
Adding Tools to Matimo: Publish a package
Testing Tools: Write tests
OAuth Setup: Add authentication

Integrating with Frameworks (LangChain, CrewAI, etc.)

Architecture Overview: Understand patterns
Framework Integrations: Integration examples
SDK Patterns: Best practices

Securing Agent Tool Usage

Policy & Lifecycle Guide: Full security setup
Meta-Tools Reference: Built-in management tools
Approval System: Approval handler config
Policy Demo (Python): 11-mission autonomous agent demo
Policy Demo (TypeScript): TypeScript equivalent
Skills Demo (Python): 6-mission skills lifecycle demo

For AI Agents (Quick Orientation)

If you are an AI agent (LangChain, CrewAI, MCP client) reading this to understand Matimo:

Read first: Meta-Tools Reference, the 15 built-in meta-tools you can call right now
Tool creation flow: matimo_validate_tool → matimo_create_tool → matimo_approve_tool → matimo_reload_tools
Skills discovery: matimo_list_skills → matimo_get_skill to load domain expertise on-demand
OpenAI 128-tool limit: If using auto_discover=True, cap your bound tool list, prioritize matimo_* tools first
Policy rules: Draft tools are blocked whenever the context environment string contains “prod” (case-insensitive substring match, "prod", "production", "PRODUCTION-us-east" all match), and in any other environment they run only for a caller with the admin role; approve a tool with matimo_approve_tool to use it normally. Command tools, HTTP DELETE tools and tools with requires_approval: true ask a human before every call. SSRF-blocked URL patterns are rejected by the content validator both at creation/approval time and again at execution time against the fully-resolved URL.
Errors: All errors are MatimoError with typed ErrorCode. Check error.code for programmatic handling.
Examples to study: python/examples/native/meta_flow/meta_tools_integration.py is the canonical end-to-end reference.

Contributing Code

Start here: Contributing Guidelines
Clone repo and set up locally
Commit Guidelines: Proper commit format
Development Standards: Code quality rules
Open PR and request review

Maintaining/Reviewing

Development Standards: Review checklist
Contributing Guidelines: PR requirements
Commit Guidelines: Validate commits
Architecture Overview: Understand design decisions

Documentation Structure

docs/
├── index.md                      # This file, documentation index
├── RELEASES.md                   # Release notes and changelog
├── ROADMAP.md                    # Project roadmap
├── MCP.md                        # MCP server setup and Claude Desktop
├── COMPOSIO.md                   # Governed Composio catalog
├── mcp/                          # MCP setup, quick reference, maintenance
├── notebooks/                    # Colab notebooks (00_index … 05_mcp_server)
├── getting-started/
│   ├── QUICK_START.md            # 5-minute setup (TypeScript + Python)
│   ├── installation.md           # Detailed installation
│   └── YOUR_FIRST_TOOL.md        # Create your first tool
├── api-reference/
│   ├── SDK.md                    # Complete SDK API (TypeScript + Python)
│   ├── ERRORS.md                 # Error handling and error codes
│   ├── TYPES.md                  # TypeScript type definitions
│   ├── META_TOOLS.md             # Built-in meta-tools reference (15 tools)
│   ├── POLICY_AND_LIFECYCLE.md   # Policy engine and tool lifecycle
│   ├── APPROVAL-SYSTEM.md        # Approval handler configuration
│   └── LOGGING.md                # Logger API and formats
├── tool-development/
│   ├── TOOL_SPECIFICATION.md     # YAML tool schema reference
│   ├── YAML_TOOLS.md             # YAML tool writing guide
│   ├── ADDING_TOOLS.md           # Creating tool provider packages
│   ├── DECORATOR_GUIDE.md        # TypeScript decorators
│   ├── TESTING.md                # Testing tools
│   ├── TOOL_WORKFLOW.md          # Step-by-step tool checklist
│   ├── HTTP_PARAMETER_EMBEDDING.md # HTTP parameter encoding
│   └── PROVIDER_CONFIGURATION.md # Multi-provider setup
├── framework-integrations/
│   ├── LANGCHAIN.md              # LangChain (Python + TypeScript)
│   ├── CREWAI.md                 # CrewAI multi-agent (Python)
│   ├── AGNO.md                   # Agno agents/teams/workflows (Python)
│   ├── BRUNO.md                  # Bruno API testing
│   └── VERCEL_AI.md              # Vercel AI SDK (TypeScript)
├── skills/
│   ├── SKILLS.md                 # Skills system guide
│   └── TFIDF_SEMANTIC_SEARCH.md  # TF-IDF implementation details
├── architecture/
│   ├── OVERVIEW.md               # System design and patterns
│   └── OAUTH.md                  # OAuth2 implementation
├── user-guide/
│   ├── SDK_PATTERNS.md           # Factory, decorator, framework patterns
│   ├── TOOL_DISCOVERY.md         # Auto-discovery and search
│   ├── AUTHENTICATION.md         # API keys, OAuth2, token management
│   └── DEVELOPMENT_STANDARDS.md  # Code quality rules
├── community/
│   └── COMMIT_GUIDELINES.md      # Conventional commits
└── troubleshooting/
    └── FAQ.md                    # Common questions & solutions

Python examples (python/examples/):
├── native/                       # Factory, decorator + advanced agent demos
│   ├── policy/policy_demo.py     # 11-mission policy + HITL lifecycle
│   ├── skills/skills_demo.py     # 6-mission skills lifecycle
│   ├── meta_flow/meta_tools_integration.py  # 5-mission meta-tools lifecycle
│   └── logger_example.py         # Logging demo (no API key needed)
├── langchain/                    # LangChain agents, per provider
├── crewai/                       # CrewAI agents, per provider
├── agno/                         # Agno agents
├── bruno/                        # Bruno collections as governed tools
└── mcp/                          # MCP server and client (own uv project)

TypeScript examples (typescript/examples/tools/):
├── <provider>/                   # factory, decorator, langchain, with-approval per provider
├── policy/policy-demo.ts         # 11-mission policy lifecycle
├── skills/skills-demo.ts         # Skills lifecycle + TF-IDF
├── meta-flow/meta-tools-integration.ts  # Meta-tools lifecycle
└── agents/langchain-skills-policy-agent.ts  # Production agent pattern

Key Concepts

Tools

Tools are the building blocks of Matimo. They define what can be executed, what parameters they accept, and how they run.

YAML Tools: Declarative tool definitions (see Tool Specification)
Decorators: @tool('name') class methods that call a loaded YAML tool (see Decorator Guide)

Executors

Executors run tools with different backends:

HttpExecutor: type: http, REST calls (the default)
FunctionExecutor: type: function, a co-located .ts/.js or .py file
CommandExecutor: type: command, shell CLIs (asks for approval on every call)

See API Reference for details.

SDK

Load tools and execute them:

import { MatimoInstance } from '@matimo/core';

const matimo = await MatimoInstance.init({ autoDiscover: true });
const result = await matimo.execute('calculator', { operation: 'add', a: 2, b: 3 });

from matimo import Matimo

matimo = await Matimo.init(auto_discover=True)
result = await matimo.execute("calculator", {"operation": "add", "a": 2, "b": 3})

See Quick Start and API Reference.

MCP Server

Matimo can run as an MCP server, allowing Claude and other clients to discover and use tools:

npx matimo mcp                 # stdio, for Claude Desktop / Cursor

import { createMCPServer } from '@matimo/core/mcp';

const server = await createMCPServer({ transport: 'http', port: 3000, autoDiscover: true });

See MCP.md for client configuration, HTTP mode and Python.

Standards & Practices

Code Quality

TypeScript: Strict mode enforced (no any)
Testing: TypeScript coverage floors enforced (lines 95%, functions 97%, branches 87%, statements 95%); CI also enforces a 95% floor on matimo-core (Python)
Linting: ESLint with automatic formatting
Documentation: JSDoc comments for all public APIs

See Development Standards.

Commits

Format: Conventional Commits (type(scope): subject)
Types: feat, fix, docs, refactor, test, chore, perf, style, ci, revert, example
Examples: “feat(executor): add HTTP support”, “fix(schema): validate enums”

See Commit Guidelines.

Pull Requests

Follow TDD approach (test first, implement after)
Keep PRs focused (one feature/fix per PR)
Ensure tests pass and the coverage floors hold
Follow code standards and get code review

See Contributing Guidelines.

Common Tasks

Write a YAML Tool

Create tools/<tool-name>/definition.yaml (name matches the directory)
Follow the Tool Specification schema
Include parameters and execution; add authentication if needed
Run pnpm validate-tools
Follow the Tool Workflow for tests and examples in both SDKs

Write a Decorator Tool

Load the YAML tool with MatimoInstance.init(...) and call setGlobalMatimoInstance(matimo)
Add a class method decorated with @tool('tool-name')
Calling the method executes the tool through the policy engine
Follow Decorator Guide patterns

Integrate with LangChain

See Framework Integrations for patterns
Check typescript/examples/tools/ and python/examples/langchain/ for working examples
Follow Architecture Overview for design decisions

Contribute Code

Fork and clone repository
Create feature branch: git checkout -b feat/description
Write tests first (TDD)
Implement feature
Follow Development Standards
Commit using Commit Guidelines
Push and create PR
Follow Contributing Guidelines checklist

Need Help?

Questions? Check relevant documentation or open a GitHub Discussion
Found a bug? Open an issue
Troubleshooting? See FAQ
Want to contribute? See Contributing Guidelines

Documentation Note: While I strive for accuracy and completeness, this documentation may contain oversights, outdated information, or areas needing improvement, due to my limitations. If you notice any errors, missing information, or have suggestions for enhancement, please help me to improve! See our Contributing Guidelines to learn how to submit corrections and improvements. Your contributions to documentation are highly valued! Thank you.

Last updated: October 2026