matimo: Instructions file for Claude Code

Matimo — CLAUDE.md

Framework-agnostic, policy-governed tool-execution SDK for AI agents. Define a tool once in YAML and deploy it to LangChain, CrewAI, MCP, OpenAI, and Claude. MIT licensed, dual TypeScript + Python implementation at feature parity. Competitor: Composio. A separate hosted product, Matimo Workbench, builds on top of this governance layer with a visual builder — out of scope for this repo.

Package manager: pnpm 8.15.0 | Node: ≥18 | Python: 3.11

What this is

Governance-first: every tool call (built-in, third-party, or agent-created) passes through a policy engine (risk classification low/medium/high/critical, deterministic security rules, HITL quarantine) before executing. On top of that: 129 tools across 10 provider packages (plus a governed Composio catalog for third-party reach), 15 meta-tools for runtime self-extension (matimo_create_tool, matimo_create_skill, matimo_reload_tools, and 12 more), and one YAML tool definition that runs across TS, Python, LangChain, CrewAI, and MCP.

Workspace structure

Root packages/ and root examples/ are dead leftovers — do not add files there. The TypeScript SDK was restructured into typescript/ (commit dfefb3c, "restructure monorepo into typescript/python directories"). Verified directly: git ls-files packages/ and git ls-files examples/ both return 0 — nothing under either root directory is git-tracked. What's physically on disk there (dist/, node_modules/, tsconfig.tsbuildinfo) is stale local build output from before the restructure. There is no pnpm-workspace.yaml at repo root and root package.json is only a 3-line devDependency shim (commitlint, husky). The active TS workspace config is typescript/pnpm-workspace.yaml; run all pnpm commands from typescript/, not repo root. Real examples live in typescript/examples/ and python/examples/.

typescript/                   # THE active pnpm workspace — TypeScript SDK
  pnpm-workspace.yaml         # Authoritative list of active packages
  packages/
    core/
      src/                    # TypeScript source (approval, auth, core, executors, mcp, policy…)
      tools/                  # Built-in YAML tools (calculator, read, web, matimo_* meta-tools)
      skills/                 # Core Matimo SKILL.md files (tool-creation, policy-validation…)
      test/                   # Jest unit + integration tests
    cli/                      # matimo CLI — src/, test/
    slack/                    # Slack tools — tools/, skills/, test/
    gmail/                    # Gmail tools — tools/, skills/, test/
    github/                   # GitHub tools — tools/, skills/
    hubspot/                  # HubSpot tools — tools/, skills/, test/
    notion/                   # Notion tools — tools/, skills/, test/
    postgres/                 # SQL tools — tools/, skills/, test/
    twilio/                   # Twilio SMS/MMS — tools/, skills/, test/
    mailchimp/                # Mailchimp tools — tools/, skills/, test/
    microsoft/                # Microsoft tools
    composio/                 # Composio-routed third-party tools (never call it a "proxy" — see wording note below)
    bruno/                    # WIP package
  examples/
    tools/                    # Per-provider: factory, decorator, langchain, with-approval
    mcp/                      # MCP server examples
python/                       # Python SDK — full feature parity with typescript/
  pyproject.toml              # uv workspace root
  packages/                   # Python package source (uv workspaces), mirrors typescript/packages/ 1:1
  examples/
    native/                   # Direct SDK — mirrors TS factory pattern
    langchain/                # LangChain agents (Python)
    crewai/                   # CrewAI agents
    mcp/                      # MCP server usage (own uv lockfile — separate uv project)
docs/                         # Full docs site: getting-started, api-reference, architecture, tool-development, framework-integrations, mcp, skills
packages/                     # DEAD — untracked leftover build output, not a workspace. Do not add files here.
examples/                     # DEAD — untracked leftover, not a workspace. Do not add files here.