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 Agents To Extentend Itsel.. Most SDKs give agents tools. Matimo gives agents the ability to build new tools — validated, approved, and live — without restarting. The meta-tool layer is Matimo’s core differentiator.

A framework-agnostic SDK with pre-built provider tools, a skills knowledge layer, MCP out of the box, and agents that autonomously build new capabilities — governed by a policy engine you control

Complete documentation for Matimo.

⚡ Getting Started

  1. Quick Start — 5-minute setup (npm install → first tool execution)
  2. Your First Tool — Create and test a basic YAML tool
  3. API Reference — Understand the SDK fundamentals

Then explore Three Integration Patterns to see what’s possible.

📦 Full Installation & Requirements

Reference

🟢 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 (80%+ minimum)
    • ESLint and Prettier
    • JSDoc documentation

Development & Advanced Usage

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 — 11-mission autonomous agent demo
  5. Skills Demo — 5-mission skills lifecycle demo

👨‍💻 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

🟢 For First-Time Users

  1. Start with Quick Start for setup
  2. Try Your First Tool to create a tool
  3. Check API Reference for SDK usage
  4. See Tool Specification to write tools
  5. Review Architecture Overview to understand design

For Tool Writers

  1. Read Tool Specification for YAML tools
  2. See Adding Tools to Matimo to publish packages
  3. Follow Development Standards for code quality

For Framework Integration

  1. Check Framework Integrations for LangChain/CrewAI
  2. See Architecture Overview for integration patterns
  3. Review examples in examples/ directory

For Contributors

  1. Check Contributing Guidelines for contribution guidelines
  2. Follow Development Standards for code quality
  3. Use Commit Guidelines for proper commit format

For Maintainers

  1. Review Development Standards for quality metrics
  2. Check Commit Guidelines for PR commit validation
  3. See Contributing Guidelines for overall workflow

Documentation Structure

docs/
├── index.md                      # This file - documentation index
├── RELEASES.md                   # Release notes and changelog
├── ROADMAP.md                    # Project roadmap
├── getting-started/
│   ├── QUICK_START.md            # 5-minute setup guide
│   ├── installation.md           # Detailed installation instructions
│   └── YOUR_FIRST_TOOL.md        # Create your first tool
├── api-reference/
│   ├── SDK.md                    # Complete SDK API
│   ├── ERRORS.md                 # Error handling and error codes
│   ├── TYPES.md                  # TypeScript type definitions
│   ├── META_TOOLS.md             # Built-in meta-tools reference
│   ├── POLICY_AND_LIFECYCLE.md   # Policy engine and tool lifecycle
│   ├── APPROVAL-SYSTEM.md        # Approval handler configuration
│   └── LOGGING.md                # Winston logger integration
├── tool-development/
│   ├── TOOL_SPECIFICATION.md     # YAML tool schema
│   ├── YAML_TOOLS.md             # YAML tool writing guide
│   ├── ADDING_TOOLS.md           # Creating tool packages
│   ├── DECORATOR_GUIDE.md        # TypeScript decorators
│   ├── TESTING.md                # Testing tools
│   └── PROVIDER_CONFIGURATION.md # Multi-provider setup
├── framework-integrations/
│   └── LANGCHAIN.md              # LangChain & framework patterns
├── architecture/
│   ├── OVERVIEW.md               # System design and patterns
│   └── OAUTH.md                  # OAuth2 implementation
├── user-guide/
│   ├── SDK_PATTERNS.md           # SDK usage patterns
│   ├── TOOL_DISCOVERY.md         # Discovering tools
│   ├── AUTHENTICATION.md         # Authentication setup
│   └── DEVELOPMENT_STANDARDS.md  # Code quality rules
├── community/
│   └── COMMIT_GUIDELINES.md      # Conventional commits
└── troubleshooting/
    └── FAQ.md                    # Common questions & solutions

Root-level files:
├── [CONTRIBUTING.md](https://github.com/tallclub/matimo/blob/main/CONTRIBUTING.md) — Contribution guidelines
├── [SECURITY.md](https://github.com/tallclub/matimo/blob/main/SECURITY.md) — Security policy
└── [README.md](https://github.com/tallclub/matimo/blob/main/README.md) — Project overview

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