odoo-toolbox

Battle-tested Odoo knowledge for AI agents, validated against real Odoo v17 instances in CI.

odoo-toolbox teaches AI agents (Claude Code, Cursor, etc.) how to work with Odoo ERP. It provides tested knowledge modules, a TypeScript RPC client, and schema introspection tools.

Knowledge Modules

The skills/odoo/ directory contains the core product — progressive, tested documentation that AI agents load on demand:

Module	What it teaches
connection	Authentication and session management
field-types	Odoo type system and read/write asymmetry
domains	Query filter syntax and composition
crud	Create, Read, Update, Delete operations
search	Search and filtering patterns
introspection	Discover models and fields dynamically
properties	Dynamic user-defined fields
modules	Module lifecycle management

Plus: mail system (chatter, activities, discuss), timesheets, MIS Builder.

All code examples are extracted and tested against real Odoo v17 in CI.

Quick Start

Option 0: Install via skills.sh (recommended)

If you're using the skills CLI (skills.sh), install directly from GitHub:

npx -y skills add marcfargas/odoo-toolbox --all

This will install the skills into your agent's skills directory (typically under ~/.pi/agent/skills/).

Option 1: Download Pre-built Skills

Download odoo-skills.zip from the latest GitHub release (recommended) or from the latest CI build artifacts.

unzip odoo-skills.zip
cd odoo-skills
cp .env.example .env  # Add your Odoo credentials

Option 2: Scaffold a Custom Skill Project

npx @marcfargas/create-odoo-skills my-odoo-skills
cd my-odoo-skills
cp .env.example .env  # Configure your Odoo credentials

Then point your AI agent to the project and ask it to connect, introspect, and work with your Odoo instance.

TypeScript Packages

The skills are backed by tested TypeScript infrastructure:

Package	Description	Status
@marcfargas/odoo-client	Lightweight RPC client for Odoo	Active
@marcfargas/odoo-introspection	Schema introspection and type generation	Active
@marcfargas/create-odoo-skills	CLI to scaffold skill projects	Active
@marcfargas/odoo-cli	CLI for Odoo ERP — 10 command groups (records, mail, modules, attendance, timesheets, accounting…)	Active
@marcfargas/odoo-state-manager	Drift detection and plan/apply (Terraform-style)	Experimental
@marcfargas/odoo-test-harness	Testcontainers-based Odoo testing infrastructure	In development

CLI Quick Start

Run Odoo operations directly from the terminal with @marcfargas/odoo-cli:

npx @marcfargas/odoo-cli --help

# Set credentials via environment or .env
export ODOO_URL=https://myodoo.example.com
export ODOO_DB=mydb
export ODOO_USERNAME=admin
export ODOO_PASSWORD=secret

# Search records
odoo records search res.partner --domain '[["is_company","=",true]]' --limit 5

# Install a module
odoo modules install sale_management

# Post a note on a record
odoo mail note crm.lead 42 "Called — follow-up scheduled"

The CLI provides 10 command groups: records, mail, modules, attendance, timesheets, accounting, config, state, schema, and run.

Prerequisites

• Node.js ≥ 18
• Odoo v17 instance (for integration tests / real usage)

Contributing

git clone https://github.com/marcfargas/odoo-toolbox.git
cd odoo-toolbox
npm install
npm test

See DEVELOPMENT.md for setup, testing, and contribution guidelines. See AGENTS.md for AI assistant coding conventions. See docs/ for developer documentation (architecture, service patterns, API guides).

License

Code (packages/): LGPL-3.0

Skills (skills/): CC0 1.0 Universal — public domain. Use the knowledge freely in any project, commercial or not, with no attribution required. AI agents, companies, competing projects — zero restrictions, zero friction.

Bugs & Support

GitHub Issues