Lean local helper for managing pi skills in Odoo projects.

osmo = Odoo Skill Management tOol

The final O in osmo (from tOol) is an easter egg aligned with the octo / otto naming style.

• TUI-first DX for humans (clear, friendly, low-friction)
• CLI-first determinism for agents (json-friendly, scriptable, reliable)
• One clear setup path (KISS)
• Shared skills stay consistent across docs, manifest, and defaults
• Distribution standard for tools: pipx

• docs/releases/README.md
• docs/releases/v0.2.0.md
• docs/releases/RELEASE_CHECKLIST.md

• docs/operator-cheatsheet.md

• lazygit
• lazydocker
• k9s
• otto

Target feel: keyboard-first, readable, calm defaults, strong feedback loops.

• python3 (with venv)
• direnv
• pipx

Install direnv with your OS package manager (examples):

• macOS (Homebrew): brew install direnv
• Ubuntu/Debian: sudo apt-get update && sudo apt-get install -y direnv
• Fedora: sudo dnf install -y direnv
• Arch: sudo pacman -S direnv
• Windows: winget install direnv.direnv (or choco install direnv / scoop install direnv)

If pipx is missing:

python3 -m pip install --user pipx
python3 -m pipx ensurepath

Run this exact sequence after cloning:

# 1) install the CLI globally (isolated via pipx)
pipx install --editable .

# 2) create repo-local venv and install deps
./scripts/bootstrap.sh

# 3) enable auto-activation of .venv for this repo
direnv allow

# 4) install local git hooks
./scripts/install-git-hooks.sh

# 5) verify setup
./scripts/smoke-test.sh

Why this is the recommended path:

• pipx makes osmo available in your shell PATH everywhere, so humans and agents can call the same command consistently.
• pipx isolates the CLI in its own environment, preventing global Python package conflicts.
• bootstrap.sh keeps repo dependencies inside .venv, so installs do not leak into system Python.
• direnv allow auto-activates .venv whenever you enter the repo, including new terminals (no manual re-activation step).
• hooks + smoke provide deterministic quality gates before commits.

Update:

pipx upgrade osmo

Uninstall:

pipx uninstall osmo

cd /path/to/osmo
# direnv auto-activates .venv
./scripts/smoke-test.sh
osmo

If dependencies change (requirements.txt updates), rerun:

./scripts/bootstrap.sh

Why this matters:

• Humans and agents should run the same executable: osmo.
• This avoids “works in one shell, fails in another” issues.
• It keeps automation deterministic.

Human-first (interactive):

osmo

Agent-first (deterministic CLI):

osmo wizard /path/to/odoo-project --dry-run --output json
osmo doctor /path/to/odoo-project --output json
osmo cleanup /path/to/odoo-project --dry-run --output json
osmo reset-project-path --dry-run --output json
osmo wizard --describe --output json
osmo doctor --describe --output json

Run the skill manager without arguments:

osmo

This opens the interactive TUI (default experience).

Layout is stack-based for readability (otto-like):

• Mode + filter bar (top)
• Use-cases hint bar
• Skills table (count/name/state)
• Selected skill details
• Doctor + status panel
• Status footer

• ↑/↓ or j/k — move selection
• Enter / Space — toggle selected skill
• e — enable selected skill
• d — disable selected skill
• s — run quick setup
• c — cleanup/uninstall osmo-managed project artifacts (with confirm)
• x — quick doctor summary + top fix suggestions
• X — full doctor report in terminal
• r — refresh
• q — quit

Path-aware commands support explicit project targeting.

Wizard/doctor/cleanup resolve project path by:

1. explicit argument (if provided), or
2. saved default from .envrc.local (ODOO_REPO_PATH), or
3. interactive prompt.

Runtime commands (components, enable-skill, disable-skill, up, db, shell, test, lint) support:

• --project /path/to/odoo-project (recommended for deterministic automation)
• otherwise cwd-based auto-detection.

You can clear saved path with:

osmo reset-project-path

Both doctor modes give guidance, not only status:

• what failed/warned
• what to do next
• concrete follow-up commands when relevant
• JSON mode includes checks_structured[] (check_code, category, resource, severity, ...)
• JSON mode includes recommendations_structured[] with code, severity, message, next_command

Use quick x for in-TUI guidance, and X when you want the full report.

The TUI is primary. Command mode is agent-friendly for deterministic automation:

osmo --help
osmo help --output json
osmo ui [PROJECT_REPO_PATH]
osmo wizard [PROJECT_REPO_PATH]
osmo wizard [PROJECT_REPO_PATH] --dry-run --output json
osmo wizard --describe --output json
osmo doctor [PROJECT_REPO_PATH]
osmo doctor [PROJECT_REPO_PATH] --output json
osmo doctor --describe --output json
osmo cleanup [PROJECT_REPO_PATH]
osmo components --project /path/to/odoo-project --output json
osmo enable-skill dev-workbench --project /path/to/odoo-project --dry-run --output json
osmo disable-skill dev-workbench --project /path/to/odoo-project --dry-run --output json
osmo up --project /path/to/odoo-project
osmo reset-project-path --dry-run --output json
osmo reset-project-path --describe --output json

Automation contract (JSON/describe/dry-run where mutating):

• wizard, doctor, cleanup, components, enable-skill, disable-skill, reset-project-path

Human-ops commands (intentionally outside automation contract):

• ui, new-skill, up, db, shell, test, lint

Stable contract spec:

• docs/cli-contract.md

You can inspect command scope machine-readably via:

osmo help --output json

Look for:

• data.contract_version
• data.contract_spec
• data.details[].params[]

Use the global osmo command (installed via pipx):

osmo

The skill manager installs shared skills into your project via symlinks (not file copies).

• shared skills symlink directory:
  • <odoo-project>/.pi/skills/shared-osmo/<skill> → <skill-manager-root>/skills/<skill>

Why this is useful:

• one source of truth in the skill manager repo
• instant skill updates across linked projects
• easy cleanup/uninstall

Local hygiene behavior:

• the tool can add .pi/ to local git exclude (.git/info/exclude)
• this is local-only and not committed

Current shared skills in this skill manager:

• dev-workbench
• local-db
• semantic-commit-message
• odoo-otto
• odoo-log-debug
• odoo-pr-review
• odoo-shell-debug
• odoo-ui-check
• skill-authoring
• web-lookup

Browser JS helpers used by odoo-ui-check are in:

• skills/browser-tools/browser-tools/

./scripts/smoke-test.sh

Smoke uses .venv/bin/python and checks:

• CLI help/guardrails
• skill metadata consistency (skills/, manifest, docs, defaults)
• CLI contract behavior (scripts/test-cli-contracts.sh)
• golden JSON snapshots (scripts/test-cli-golden.sh)

Install once:

./scripts/install-git-hooks.sh

This enables a local pre-commit hook that runs the smoke test before each commit.