--- slug: "marcfargas-odoo-skills" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/marcfargas/odoo-toolbox@master/README.md" repo: "https://github.com/marcfargas/odoo-toolbox" source_file: "README.md" branch: "master" --- # 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/`](https://github.com/marcfargas/odoo-toolbox/tree/HEAD/skills/odoo/) directory contains the core product — progressive, tested documentation that AI agents load on demand: | Module | What it teaches | |--------|-----------------| | [connection](https://github.com/marcfargas/odoo-toolbox/blob/HEAD/skills/odoo/base/connection.md) | Authentication and session management | | [field-types](https://github.com/marcfargas/odoo-toolbox/blob/HEAD/skills/odoo/base/field-types.md) | Odoo type system and read/write asymmetry | | [domains](https://github.com/marcfargas/odoo-toolbox/blob/HEAD/skills/odoo/base/domains.md) | Query filter syntax and composition | | [crud](https://github.com/marcfargas/odoo-toolbox/blob/HEAD/skills/odoo/base/crud.md) | Create, Read, Update, Delete operations | | [search](https://github.com/marcfargas/odoo-toolbox/blob/HEAD/skills/odoo/base/search.md) | Search and filtering patterns | | [introspection](https://github.com/marcfargas/odoo-toolbox/blob/HEAD/skills/odoo/base/introspection.md) | Discover models and fields dynamically | | [properties](https://github.com/marcfargas/odoo-toolbox/blob/HEAD/skills/odoo/base/properties.md) | Dynamic user-defined fields | | [modules](https://github.com/marcfargas/odoo-toolbox/blob/HEAD/skills/odoo/base/modules.md) | Module lifecycle management | Plus: [mail system](https://github.com/marcfargas/odoo-toolbox/tree/HEAD/skills/odoo/mail/) (chatter, activities, discuss), [timesheets](https://github.com/marcfargas/odoo-toolbox/blob/HEAD/skills/odoo/modules/timesheets.md), [MIS Builder](https://github.com/marcfargas/odoo-toolbox/blob/HEAD/skills/odoo/oca/mis-builder.md). 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: ```bash 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](https://github.com/marcfargas/odoo-toolbox/releases) (recommended) or from the [latest CI build](https://github.com/marcfargas/odoo-toolbox/actions) artifacts. ```bash unzip odoo-skills.zip cd odoo-skills cp .env.example .env # Add your Odoo credentials ``` ## TypeScript Packages The skills are backed by tested TypeScript infrastructure. The monorepo splits into **libraries** (`packages/`) you import and **targets** (`targets/`) you run. ### Libraries | Package | Description | Status | |---------|-------------|--------| | [@marcfargas/odoo-client](https://github.com/marcfargas/odoo-toolbox/tree/HEAD/packages/odoo-client) | Lightweight RPC client for Odoo | Active | | [@marcfargas/odoo-introspection](https://github.com/marcfargas/odoo-toolbox/tree/HEAD/packages/odoo-introspection) | Schema introspection and type generation | Active | | [@marcfargas/odoo-testcontainers](https://github.com/marcfargas/odoo-toolbox/tree/HEAD/packages/odoo-testcontainers) | Testcontainers-based Odoo testing infrastructure | Active | | [@marcfargas/odoo-state-manager](https://github.com/marcfargas/odoo-toolbox/tree/HEAD/packages/odoo-state-manager) | Drift detection and plan/apply (Terraform-style) | Experimental | ### Targets | Package | Description | Status | |---------|-------------|--------| | [@marcfargas/odoo-cli](https://github.com/marcfargas/odoo-toolbox/tree/HEAD/targets/odoo-cli) | CLI for Odoo ERP — 10 command groups (records, mail, modules, attendance, timesheets, accounting…) | Active | | [@marcfargas/odoo-mcp](https://github.com/marcfargas/odoo-toolbox/tree/HEAD/targets/odoo-mcp) | MCP server for Odoo | Active | ## CLI Quick Start Run Odoo operations directly from the terminal with `@marcfargas/odoo-cli`: ```bash 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** ≥ 24 - **Odoo** v17 instance (for integration tests / real usage) ## Contributing ```bash git clone https://github.com/marcfargas/odoo-toolbox.git cd odoo-toolbox npm install npm test ``` See [DEVELOPMENT.md](https://github.com/marcfargas/odoo-toolbox/blob/HEAD/DEVELOPMENT.md) for setup, testing, and contribution guidelines. See [AGENTS.md](https://github.com/marcfargas/odoo-toolbox/blob/HEAD/AGENTS.md) for AI assistant coding conventions. See [`docs/`](https://github.com/marcfargas/odoo-toolbox/tree/HEAD/docs/) for developer documentation (architecture, service patterns, API guides). ## License **Code** (`packages/`, `targets/`): [LGPL-3.0](https://github.com/marcfargas/odoo-toolbox/tree/HEAD/LICENSE) **Skills** (`skills/`): [CC0 1.0 Universal](https://github.com/marcfargas/odoo-toolbox/tree/HEAD/skills/odoo/LICENSE) — **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](https://github.com/marcfargas/odoo-toolbox/issues)