Quick Start — 5 Minutes

Get Matimo up and running in 5 minutes.

Choose Your Path

Not sure where to start? Pick one:

🚀 Path A: Use Pre-Built Tools (Fastest — 2 mins)

You want to execute existing tools (Slack, Gmail, GitHub, etc.) without building your own.

Install:

npm install matimo @matimo/slack @matimo/gmail

Use immediately:

import { MatimoInstance } from 'matimo';

const matimo = await MatimoInstance.init({ autoDiscover: true });

// Execute a Slack tool
const result = await matimo.execute('slack-send-message', {
  channel: '#general',
  text: 'Hello from Matimo!',
});

console.log('Message sent!', result);

✅ Great for: Using existing integrations in your app 📖 See All Available Tools →

🛠️ Path B: Build Your Own Tool (Educational — 5 mins)

You want to understand how to create and execute custom tools.

Continue below to create a calculator tool →

✅ Great for: Learning how Matimo works 📖 Build Your First Tool →

🤖 Path C: Integrate with LangChain (Advanced — 10 mins)

You want to use Matimo tools with an AI agent (LangChain, CrewAI, etc.).

See LangChain Integration →

✅ Great for: Building intelligent agents 📖 Examples →

1. Installation (1 min)

npm install matimo
# or with pnpm
pnpm add matimo

2. Create Your First Script (3 min)

Create a file demo.ts:

import { MatimoInstance } from 'matimo';

async function main() {
  // Initialize Matimo with your tools
  const matimo = await MatimoInstance.init('./tools');

  // List available tools
  const tools = matimo.listTools();
  console.log(`📦 Loaded ${tools.length} tools`);

  // Execute a tool
  const result = await matimo.execute('calculator', {
    operation: 'add',
    a: 10,
    b: 5,
  });

  console.log('✅ Result:', result);
}

main().catch(console.error);

3. Create Your First Tool (1 min)

Create tools/calculator/definition.yaml:

name: calculator
description: Perform basic math operations
version: '1.0.0'

parameters:
  operation:
    type: string
    enum: [add, subtract, multiply, divide]
    required: true
    description: Mathematical operation to perform
  a:
    type: number
    required: true
    description: First operand
  b:
    type: number
    required: true
    description: Second operand

execution:
  type: command
  command: node
  args:
    - -e
    - |
      const op = process.argv[1];
      const a = parseFloat(process.argv[2]);
      const b = parseFloat(process.argv[3]);
      const ops = { add: a + b, subtract: a - b, multiply: a * b, divide: a / b };
      console.log(JSON.stringify({ result: ops[op] }));
    - '{operation}'
    - '{a}'
    - '{b}'

output_schema:
  type: object
  properties:
    result:
      type: number
      description: Result of the operation
  required: [result]

error_handling:
  retry: 2
  backoff_type: exponential
  initial_delay_ms: 100

4. Run It (< 1 min)

# Compile TypeScript
npx tsc demo.ts

# Run the script
node demo.js

# Output:
# 📦 Loaded 1 tools
# ✅ Result: { result: 15 }

What Just Happened?

MatimoInstance.init(‘./tools’) — Loaded all YAML files from ./tools/**/*.yaml
matimo.listTools() — Listed discovered tools
matimo.execute(‘calculator’, {…}) — Executed the tool with parameters
Matimo validated parameters, spawned process, validated output, returned result

Next Steps

Choose Your Pattern

Factory Pattern (you just used this) — Best for simple scripts and backends
Decorator Pattern — Best for class-based code
LangChain — Best for AI agents with automatic tool selection

See SDK Usage Patterns for details.

Add More Tools

Create more YAML files in tools/:

tools/
├── calculator/
│   └── definition.yaml      # Done ✅
├── my-api/
│   └── definition.yaml      # Create more
└── slack/
    └── definition.yaml

Each tool is just a YAML file — no code needed!

Use Provider Tools

Install pre-built tools from npm:

pnpm add @matimo/slack @matimo/gmail

Then load them alongside your custom tools:

const matimo = await MatimoInstance.init([
  './tools',                    # Your custom tools
  './node_modules/@matimo/slack/tools',  # Pre-built tools
  './node_modules/@matimo/gmail/tools'
]);

Common Tasks

List All Loaded Tools

const tools = matimo.listTools();
tools.forEach((tool) => {
  console.log(`${tool.name} - ${tool.description}`);
});

Get Tool by Name

const tool = matimo.getTool('calculator');
if (tool) {
  console.log('Parameters:', tool.parameters);
}

Search Tools

const results = matimo.searchTools('calculate');
console.log(
  'Found:',
  results.map((t) => t.name)
);

Execute with Error Handling

try {
  const result = await matimo.execute('calculator', {
    operation: 'divide',
    a: 10,
    b: 0,
  });
  console.log('Success:', result);
} catch (error) {
  if (error.code === 'TOOL_NOT_FOUND') {
    console.error('Tool not found:', error.message);
  } else if (error.code === 'INVALID_PARAMETERS') {
    console.error('Invalid parameters:', error.details);
  } else if (error.code === 'EXECUTION_FAILED') {
    console.error('Execution failed:', error.details);
  }
}

Example: Using Slack

After installing @matimo/slack:

import { MatimoInstance } from 'matimo';

const matimo = await MatimoInstance.init(['./tools', './node_modules/@matimo/slack/tools']);

// Execute a Slack tool
const result = await matimo.execute('slack-send-message', {
  channel: '#general',
  text: 'Hello from Matimo!',
});

console.log(result);

Troubleshooting

Tools not loading?

# Check that YAML files exist
ls tools/*/definition.yaml

# Validate YAML syntax
pnpm validate-tools

Execution failing?

// Enable detailed error messages
try {
  const result = await matimo.execute('tool-name', params);
} catch (error) {
  console.error('Full error:', JSON.stringify(error, null, 2));
}

Type errors?

# Check TypeScript compilation
npx tsc --noEmit

Matimo - AI Tools Ecosystem

Define tools once in YAML, use them everywhere