View on GitHub

Matimo - AI Tools Ecosystem

Define tools once in YAML, use them everywhere

Download this project as a .zip file Download this project as a tar.gz file

Matimo Documentation

Matimo Logo

Discord

Matimo — Enable AI Agents To Build Themselves

The First AI SDK with Meta-Tools, Policy Engine, and Human-in-the-Loop Control

Give your agents 137+ production-ready tools to start. Then activate 10 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:

Complete documentation for Matimo v0.1.0 (TypeScript & Python).

🚀 Choose Your SDK

🟦 TypeScript / Node.js

🐍 Python 🎉 Stable Release

⚡ Getting Started

TypeScript Getting Started

  1. Quick Start — 5-minute setup
  2. Your First Tool — Create a basic YAML tool
  3. API Reference — SDK fundamentals

Python Getting Started

  1. Quick Start — 5-minute setup with pip install matimo
  2. LangChain Integration — Build ReAct agents
  3. CrewAI Integration — Multi-agent orchestration
  4. API Reference — Python SDK documentation

📦 Installation & Requirements

📚 Reference (By Topic)

🟢 Core Concepts (Start Here)

🟡 Tool Development

🛡️ Policy & Lifecycle (Security)

🔴 Advanced Topics

Project Information

👥 For Contributors

Want to contribute? Start here:

  1. Contributing Guidelines — Full contribution workflow
    • Setup and development environment
    • Code standards and best practices
    • TDD (Test-Driven Development) approach
    • Commit message format
    • PR checklist
  2. Commit Guidelines — Conventional commits standard
    • Type, scope, subject format
    • Examples for feat, fix, docs, etc.
    • Git workflow tips
  3. Development Standards — Code quality requirements
    • TypeScript strictness
    • Testing coverage (95%+ — TypeScript and Python)
    • ESLint / ruff and Prettier
    • JSDoc documentation

Development & Advanced Usage

Troubleshooting

Quick Navigation by Role

🚀 Just Getting Started (First 30 minutes)

  1. Quick Start — Install and run your first tool
  2. Your First Tool — Create a basic YAML tool
  3. API Reference — Understand the SDK basics
  4. If stuck → FAQ

🛠️ Building Tools

  1. Tool Specification — YAML schema reference
  2. Adding Tools to Matimo — Publish a package
  3. Testing Tools — Write tests
  4. OAuth Setup — Add authentication

🤖 Integrating with Frameworks (LangChain, CrewAI, etc.)

  1. Architecture Overview — Understand patterns
  2. Framework Integrations — Integration examples
  3. SDK Patterns — Best practices

🔒 Securing Agent Tool Usage

  1. Policy & Lifecycle Guide — Full security setup
  2. Meta-Tools Reference — Built-in management tools
  3. Approval System — Approval handler config
  4. Policy Demo (Python) — 11-mission autonomous agent demo
  5. Policy Demo (TypeScript) — TypeScript equivalent
  6. 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:

  1. Read first: Meta-Tools Reference — the 10 built-in tools you can call right now
  2. Tool creation flow: matimo_validate_tool → matimo_create_tool → matimo_approve_tool → matimo_reload_tools
  3. Skills discovery: matimo_list_skills → matimo_get_skill to load domain expertise on-demand
  4. OpenAI 128-tool limit: If using auto_discover=True, cap your bound tool list — prioritize matimo_* tools first
  5. Policy rules: Draft tools are blocked in environment="prod". Command tools (type: command) require explicit approval. SSRF-blocked URL patterns are rejected by the content validator.
  6. Errors: All errors are MatimoError with typed ErrorCode. Check error.code for programmatic handling.
  7. Examples to study: python/examples/native/meta_flow/meta_tools_integration.py is the canonical end-to-end reference.

👨‍💻 Contributing Code

  1. Start here: Contributing Guidelines
  2. Clone repo and set up locally
  3. Commit Guidelines — Proper commit format
  4. Development Standards — Code quality rules
  5. Open PR and request review

📖 Maintaining/Reviewing

  1. Development Standards — Review checklist
  2. Contributing Guidelines — PR requirements
  3. Commit Guidelines — Validate commits
  4. 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
├── 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 (10 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
│   ├── 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)
│   └── 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 ReAct examples (17 files)
└── crewai/                       # CrewAI examples (10 files)

TypeScript examples (typescript/examples/tools/):
├── 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.

Executors

Executors run tools with different backends:

See API Reference for details.

SDK

Use the Matimo SDK (TypeScript) to load and execute tools:

import { MatimoInstance } from 'matimo';

const matimo = await MatimoInstance.init('./tools');
const result = await matimo.execute('tool-name', { param: 'value' });

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:

// MCP Server - Coming in Phase 2
// import { MCPServer } from 'matimo/mcp';

const server = new MCPServer({ toolsPath: './tools', port: 3000 });
await server.start();

See Quick Start for setup.

Standards & Practices

Code Quality

See Development Standards.

Commits

See Commit Guidelines.

Pull Requests

See Contributing Guidelines.

Common Tasks

Write a YAML Tool

  1. Create tools/provider/tool-name.yaml
  2. Follow Tool Specification schema
  3. Include parameters, execution, output_schema
  4. Add authentication if needed
  5. Test with pnpm test

Write a Decorator Tool

  1. Create src/tools/tool-name.tool.ts
  2. Use @tool and @param decorators
  3. Implement execute() or async execute()
  4. Follow Decorator Guide patterns
  5. Add unit tests

Integrate with LangChain

  1. See Framework Integrations for patterns
  2. Check examples/tools/ for working examples
  3. Follow Architecture Overview for design decisions

Contribute Code

  1. Fork and clone repository
  2. Create feature branch: git checkout -b feat/description
  3. Write tests first (TDD)
  4. Implement feature
  5. Follow Development Standards
  6. Commit using Commit Guidelines
  7. Push and create PR
  8. Follow Contributing Guidelines checklist

Need Help?

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: February 2026