Monorepo Structure
Relevant source files
The following files were used as context for generating this wiki page:
The oh-my-pi repository is organized as a monorepo, primarily utilizing Bun as the runtime and package manager. It consists of multiple packages, native components, and centralized scripting to manage a complex agentic ecosystem. The structure is designed to support modular development while maintaining consistent standards for code intelligence, configuration, and release management across different subsystems.
Sources: packages/coding-agent/DEVELOPMENT.md:1-10, packages/coding-agent/src/prompts/agents/init.md:15-25
Workspace Layout
The repository is divided into several high-level directories that separate core logic, native bindings, and infrastructure.
| Directory | Purpose |
|---|---|
packages/ | TypeScript/JavaScript packages, including the core coding-agent (the omp CLI). |
crates/ | Rust-based native components (pi-natives). |
python/ | Python-based tools and prompts (e.g., robomp). |
scripts/ | Centralized Bun/TypeScript utilities for CI/CD, changelogs, and releases. |
.agents/ | Project-level configuration for agent skills, rules, and prompts. |
Sources: packages/coding-agent/DEVELOPMENT.md:105-115, packages/coding-agent/test/discovery/agents-monorepo-skills.test.ts:40-60, scripts/rewrite-changelog.ts:1-20
Core Package: coding-agent
The coding-agent package is the primary entry point for the omp CLI. Its internal source structure follows a functional decomposition:
- Entry Points:
cli.ts,main.ts, andsdk.ts. - Execution Backends: Found in
exec/,eval/, andssh/. - Memory Systems: Managed within
memories/andmnemopi/. - Subagent Logic: Located in
task/,swarm/, andplan-mode/.
Sources: packages/coding-agent/DEVELOPMENT.md:46-75
Hierarchy and Discovery Logic
The monorepo implements a "walk-up" discovery pattern for project-level capabilities. Agents scan from the current working directory (CWD) up to the repository root to locate configuration and skills.
This diagram illustrates how agents prioritize local .agents/ configurations before falling back to global repository settings.
Sources: packages/coding-agent/test/discovery/agents-monorepo-skills.test.ts:70-120
Discovery Priority
- Local Package:
.agents/or.agent/directories within the immediate package. - Ancestor Directories: Recursive walk-up until the
.gitroot is reached. - Repository Root: Final project-level check at the monorepo root.
- User Level: Global configuration located in the user's home directory.
Sources: packages/coding-agent/test/discovery/agents-monorepo-skills.test.ts:135-160
Build and Maintenance Scripts
The scripts/ directory contains load-bearing utilities that maintain the monorepo's integrity and manage the release lifecycle.
Release Note Aggregation
The ci-release-notes.ts script aggregates changes from per-package CHANGELOG.md files. It merges version sections based on a semver range to ensure "silent" tags (failed CI runs) do not result in lost release notes.
Changelog Management
The rewrite-changelog.ts script uses an LLM-powered process to consolidate technical implementation noise into user-facing release notes. It specifically filters for:
- User-Visible: Public APIs, breaking changes, and critical bug fixes.
- Excluded: Internal refactors, test churn, and implementation details.
Sources: scripts/rewrite-changelog.ts:15-50
Development Workflow
Development within the monorepo is standardized through package.json scripts and specific tool requirements.
| Task | Command (within package) |
|---|---|
| Typecheck | bun run check |
| Tests | bun run test |
| Fix/Lint | bun run fix |
| Build | bun run build |
Constraints:
- Developers MUST NOT invoke
tscdirectly;bun run checkis the authoritative type-checking gate. - Prompts MUST live in
.mdfiles rather than being hardcoded in TypeScript. - Bun APIs are preferred over
node:*equivalents where available.
Sources: packages/coding-agent/DEVELOPMENT.md:15-30, python/robomp/src/prompts/kickoff_pr_review.md:155-170
Conclusion
The oh-my-pi monorepo structure facilitates a multi-language, agent-driven environment. By centralizing core logic in packages/ while allowing for native and Python extensions, it balances modularity with performance. The specialized discovery logic for .agents/ ensures that project-specific rules are respected across the entire workspace, while centralized scripts maintain a high standard for release quality and documentation.
Sources: packages/coding-agent/DEVELOPMENT.md:110-140, packages/coding-agent/src/prompts/agents/init.md:5-15