matimo: Instructions file for Codex

AGENTS.md

Instructions for AI coding agents (Cursor, GitHub Copilot, Windsurf, Codex, etc.) working in this repository. Claude Code reads CLAUDE.md instead, which covers the same ground in more depth.

What this repo is

Matimo is a policy-governed tool-execution SDK for AI agents: every tool call — built-in, third-party, or agent-created — passes through a policy engine (risk classification, security rules, human-in-the-loop approval) before it runs. MIT licensed, dual TypeScript + Python implementation with feature parity.

Full narrative and API surface: README.md. Deep architecture: docs/architecture/OVERVIEW.md.

Repo layout

typescript/     pnpm workspace — packages/{core,cli,slack,github,gmail,notion,hubspot,postgres,twilio,mailchimp,microsoft,bruno,composio}
python/         uv workspace  — packages/{core,cli,matimo,<same providers except composio>} — mirrors typescript/
docs/           getting-started, api-reference, architecture, tool-development, framework-integrations, mcp, skills
typescript/examples/, python/examples/   usage examples per integration pattern (factory, decorator, LangChain, CrewAI, MCP)

Setup, build, test

TypeScript (run from typescript/):

pnpm install && pnpm build
pnpm test              # jest; pretest runs build first
pnpm test:coverage
pnpm lint / pnpm lint:fix
pnpm validate-tools    # validate all YAML tool definitions

Python (run from python/):

make install           # uv sync --all-extras --dev
make test / make test-unit / make test-integration / make test-coverage
make lint / make format / make typecheck
make validate-tools

Never run npm install inside typescript/ (it uses pnpm-lock.yaml) or pnpm/npm inside python/ (it uses uv/uv.lock) — don't cross-contaminate package managers.

Conventions an agent must follow

• Conventional Commits, lower-case type: feat, fix, docs, style, refactor, perf, test, chore, ci, revert, example. Enforced by a commitlint pre-commit hook (husky) — don't bypass with --no-verify.
• TypeScript: strict mode, ESM ("type": "module"), Node ≥22.19, pnpm ≥8.
• Python: version pinned in python/.python-version; ruff for lint/format; mypy strict on packages/core/src.
• Every tool (built-in or agent-created) needs an explicit risk classification (low/medium/high/critical) in its YAML definition — see docs/api-reference/POLICY_AND_LIFECYCLE.md.
• New provider package → mirror an existing one exactly (slack or github are the reference implementations) in both languages. Don't let TS and Python drift — ship new features to both unless told otherwise.
• 4,400+ tests, 95%+ coverage target across TS + Python — don't drop coverage on new code.
• Don't hand-edit pnpm-lock.yaml / uv.lock — regenerate via the package manager.