> ## Documentation Index > Fetch the complete documentation index at: https://comis-fix-skill-import-vetting-gate.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Packages > Package roles, key exports, and dependency relationships Comis is structured as a monorepo with 16 TypeScript packages under `packages/`. Each package has a focused responsibility and exports a public API through its package entry point. Cross-package consumers use those public exports rather than another package's internal source paths. All packages use ES modules (`"type": "module"`), strict TypeScript with `composite: true` project references, and ES2023 as the compilation target. ## Package Overview | Package | npm Name | Role | Key Exports | | ------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | shared | `@comis/shared` | Result type, utilities (zero runtime deps) | `Result`, `ok`, `err`, `tryCatch`, `fromPromise` | | core | `@comis/core` | Domain types, ports, event bus, security, config, plugins | Ports, domain types, `EventMap`, config schemas, security utils | | infra | `@comis/infra` | Pino structured logging | Logger factory, log level manager | | memory | `@comis/memory` | SQLite + FTS5 + sqlite-vec vector search | `SqliteMemoryAdapter` (implements `MemoryPort`) | | gateway | `@comis/gateway` | Hono HTTP, JSON-RPC, WebSocket, mTLS, experimental OpenAI-shaped endpoints | HTTP server, RPC dispatch, WebSocket handler | | skills | `@comis/skills` | Skill manifest, prompt skills, MCP, built-in tools, media processing | `SkillRegistry`, media preprocessor, STT/TTS/vision adapters | | scheduler | `@comis/scheduler` | Cron jobs, heartbeat checks, task extraction | Cron engine, heartbeat monitor, task extractor | | agent | `@comis/agent` | Executor, budget, circuit breaker, RAG, sessions, context engine | `PiExecutor`, session manager, budget tracker | | channels | `@comis/channels` | 11 platform adapters (Discord, Telegram, Slack, WhatsApp, Signal, iMessage, LINE, IRC, Echo, Email, Microsoft Teams) | Channel adapters, message mappers, media resolvers | | cli | `@comis/cli` | Commander.js CLI, JSON-RPC client | CLI commands, RPC client | | daemon | `@comis/daemon` | Orchestrator, observability, graph coordinator | `DaemonInstance`, wiring, graph coordinator | | observability | `@comis/observability` | Diagnostics substrate: queued writer, payload bounding, sanitization, cache-trace runtime, EventBus bridge, cache-stats aggregation and RPC | Diagnostics runtime, cache-trace recorder, stats aggregator | | observability-otel | `@comis/observability-otel` | Opt-in OpenTelemetry and Prometheus export extension | OTLP signals, Prometheus metrics exporter | | orchestrator | `@comis/orchestrator` | Inbound pipeline, execution coordination, channel-manager, command queue, routing, and cross-session messaging | Pipeline coordinator, channel manager, command router | | comis | `comisai` | Umbrella package (namespace re-exports) and `comis` CLI bin | Namespace re-exports of all sub-packages | | web | `@comis/web` | Lit + Vite + Tailwind standalone SPA | Web dashboard views and components | ### Package Roles Explained **`@comis/shared`** is the foundation. It defines the `Result` discriminated union and its utility functions. Every other package depends on `shared`, but `shared` depends on nothing. This makes it safe to import anywhere without creating circular dependencies. **`@comis/core`** is the heart of the hexagonal architecture. It defines port interfaces in `src/ports/`, Zod-validated domain types, the `TypedEventBus`, security primitives, configuration schemas, and plugin infrastructure. The `bootstrap()` function returns the core `AppContainer`. **`@comis/agent`** is the execution engine. It contains the `PiExecutor` that orchestrates LLM calls, tool execution, and response generation. It also manages sessions, budgets, circuit breakers, RAG, and context preparation. **`@comis/channels`** contains the 11 platform adapters. Each adapter lives in its own directory (e.g., `src/telegram/`, `src/discord/`) with a standard file set: adapter, message mapper, media handler, credential validator, media resolver, voice sender, and plugin wrapper. **`@comis/daemon`** is the runtime composition root. It wires the agent, channels, gateway, persistence, skills, scheduler, orchestration, logging, and observability packages; it also manages startup, shutdown, and signals. **`@comis/web`** is a standalone single-page application built with Lit web components, Vite for bundling, and Tailwind CSS for styling. It communicates with the daemon exclusively through the gateway's HTTP and WebSocket APIs. The published umbrella package is named `comisai` on npm (the directory is `packages/comis/`). It bundles all `@comis/*` workspace packages and exposes a `comis` CLI binary. Subpath imports such as `comisai/core` or `comisai/agent` are exposed via the umbrella's `exports` map. ## Dependency relationships Package manifests and TypeScript project references are the authoritative dependency graph. At a high level: * `shared` has no Comis runtime dependency; `core` depends on `shared`. * `gateway`, `channels`, `scheduler`, and `observability` build on `core` and `shared`. * `memory` and `infra` also use the observability substrate. * `agent` uses `core`, `observability`, and `scheduler`; `orchestrator` composes `agent`, `channels`, and `core`. * `skills` uses the agent and observability contracts needed by its tools and integrations. * `daemon` is the runtime composition root. `cli` uses the daemon client surface plus the core, memory, and observability APIs. * `observability-otel` is the opt-in telemetry extension; `web` is the standalone SPA; `comisai` is the umbrella package that re-exports the workspace packages. ## Package Boundary Rules These rules are mandatory across the codebase and enforced through code review and architectural convention (see AGENTS.md section 6.2). ### No Cross-Package Internal Imports Import from the package's public API, never from internal source paths. Each package exports its public surface through `dist/index.js`. This ensures that internal refactoring within a package never breaks consumers. ```typescript theme={} // Correct: import from the package's public API import type { ChannelPort, NormalizedMessage } from "@comis/core"; import { ok, err, type Result } from "@comis/shared"; // Wrong: importing internal modules // import { something } from "@comis/core/src/internal/helper"; ``` ### Keep contracts inward Core owns shared contracts and ports; runtime packages provide implementations. Cross-package imports must use declared dependencies and public exports. Cross-package lifecycle signals use `TypedEventBus` where an event is the appropriate contract. ### Inject Logger via Deps Interface Never import `@comis/infra` directly in non-infra packages. Pass a logger through the dependency injection pattern so that packages remain decoupled from the logging implementation. This also makes unit testing easier since you can inject a mock logger that captures log calls for assertions. ### ES Modules Only All packages use `"type": "module"` with `.js` extensions in import paths. There are no CommonJS modules in the codebase. Import statements use the `.js` extension even though the source files are `.ts`: ```typescript theme={} // In TypeScript source files, use .js extension for local imports import { createCircuitBreaker } from "./circuit-breaker.js"; ``` ## Build System TypeScript project references (`composite: true`) enable incremental builds across the monorepo. Each package has its own `tsconfig.json` that references its dependencies, so `pnpm build` compiles all packages in the correct order respecting the reference graph. ```bash theme={} pnpm install # Install dependencies (native: better-sqlite3, sharp) pnpm build # Build all packages (tsc per package, respects references) pnpm test # Run all unit tests (Vitest workspace) pnpm lint:security # ESLint with security rules ``` **Configuration details:** | Setting | Value | Notes | | ----------------- | --------------------------- | ------------------------------------------ | | Target | ES2023 | Modern JavaScript output | | Module resolution | NodeNext | Native ESM with `.js` extensions | | Strict mode | Enabled | All strict TypeScript checks active | | Build output | `packages/*/dist/` | Gitignored, built on CI | | Isolated modules | `true` | Compatible with esbuild and other bundlers | | Package exports | `"main": "./dist/index.js"` | Plus `"types": "./dist/index.d.ts"` | To build and test a single package: ```bash theme={} cd packages/core && pnpm build # Build one package cd packages/core && pnpm test # Test one package ``` To run a single test file from a package directory: ```bash theme={} pnpm vitest run src/path/to/file.test.ts ``` Integration tests in `test/integration/` require `pnpm build` first because they import from `dist/`, not from source. Run them with `pnpm test:integration`. ## Explore the repository Each package has a focused responsibility and a public entry point. The [architecture page](/developer-guide/architecture) explains how packages connect through ports and adapters, while the [event bus](/developer-guide/event-bus) documents cross-package lifecycle signals. To explore the codebase structure, start with `packages/core/src/ports/` for all port interface definitions, `packages/core/src/domain/` for Zod-validated domain types, and `packages/core/src/bootstrap.ts` for the composition root. ## Related How packages connect through ports and adapters Cross-package communication via typed events Setup and build instructions Back to developer guide overview