# @octocodeai/octocode-core > Canonical Octocode tool schemas, descriptions, instructions, and discovery contracts. Latest version **21.0.1** (published 2026-10-18) · MIT license · 0 weekly downloads ## Install ```sh npm install @octocodeai/octocode-core pnpm add @octocodeai/octocode-core yarn add @octocodeai/octocode-core bun add @octocodeai/octocode-core ``` ## Health **Score 60/100 (C)** — status: active. Positive: esm support; no vulnerabilities; recently updated; high maintenance score. Warnings: low downloads; no types. ## Facts | | | |---|---| | Version | 21.0.1 | | Published | 2026-10-18 | | First published | 2026-04-09 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | ESM | | Node | >=18.12.0 | | Dependencies | 1 | | Unpacked size | 1 MB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | Guy Bary | | Maintainers | bgauryy | | Keywords | octocode, mcp, core, config | ## Links - npm: https://www.npmjs.com/package/@octocodeai/octocode-core - Homepage: https://octocode.ai - npm.io page: https://npm.io/package/@octocodeai/octocode-core ## Dependencies (1) - [zod](https://npm.io/package/zod.md) ^4.6.2 ## Alternatives - [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads - [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads - [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads - [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads - [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads ## Recent versions - 21.0.1 (latest) — 2026-10-18 - 20.0.1 — 2026-10-08 - 20.0.0 — 2026-10-08 - 19.1.5 — 2026-09-22 - 19.1.4 — 2026-09-22 - 19.1.3 — 2026-09-22 - 19.1.2 — 2026-09-21 - 19.1.1 — 2026-09-21 - 19.1.0 — 2026-09-19 - 19.0.1 — 2026-09-11 - 19.0.0 — 2026-09-10 - 18.3.0 — 2026-09-01 - 18.2.0 — 2026-08-07 - 18.1.1 — 2026-08-06 - 18.1.0 — 2026-08-05 - … 26 more at https://npm.io/package/@octocodeai/octocode-core/versions ## README # @octocodeai/octocode-core Shared, versioned contracts that are independent of Octocode tool execution: - public agent-facing tool definitions with names, descriptions, executable input schemas, and schema-owned branch diagnostics; - shared research guidance rendered for each surface’s available capabilities. Import public tool contracts from `@octocodeai/octocode-core/schema`. Execution, security, provider access, availability, and response shaping belong to the Rust `@octocodeai/octocode-native` runtime; core imports no execution or native engine. ## Imports ```ts import { DIRECT_TOOL_DEFINITIONS, TOOL_NAMES, } from "@octocodeai/octocode-core/schema"; import { buildMcpInstructions } from "@octocodeai/octocode-core/mcp"; const instructions = buildMcpInstructions(); const structureSearch = DIRECT_TOOL_DEFINITIONS.find( (tool) => tool.name === TOOL_NAMES.STRUCTURE_SEARCH, ); const request = structureSearch?.inputSchema.parse({ queries: [{ operation: "files", path: "src" }], }); ``` `@octocodeai/octocode-core/mcp` exports the shared MCP and CLI instructions, published input schemas, and the deferred-tool dispatcher definition. Tool descriptions guide selection; input schemas own fields and limits. Inspect the available tools and their live schemas before constructing a call. Pass the native catalog’s `availableTools` and `selection` to the instruction builders; with neither classification route available, they omit classification guidance. CLI context and MCP servers consume `DIRECT_TOOL_DEFINITIONS`, the public projection exported from `@octocodeai/octocode-core/schema`. These definitions intentionally omit output schemas. CLI and MCP discovery therefore advertise only the agent-facing input contract. Optional `clasifyContext` selects evidence before it reaches the host on `localFetch`, `localSearch`, `ghGetFileContent`, and `ghSearchCode` when a classification API credential is configured. Its `classifiers` array contains one to five atomic evidence questions. `_selection.ts` owns the shared fields; each tool declares its assessment scope. Native uses `clasifyTemplates.ts` and the same JEV evaluator as standalone `clasify`. Search assesses captured hit snippets per file, not hidden whole-file bodies. Fetch assesses complete raw line windows. Selected evidence returns in source order with selected/excluded/unknown counts and explicit unfiltered recovery. Prefer selection for noisy local search, large local fetches and scoped GitHub fetches. Keep exact reads, GitHub search and AST/LSP identity checks ordinary. Questions cannot recover a lexical miss. Optional `mainGoal` and `reasoning` add context without activating selection. Omit `clasifyContext` for ordinary retrieval. Public `clasify` additionally follows its beta and tool-list gates. The retired top-level `goals`, `classifiers`, and ranking controls have no aliases. `TOOL_NAMES`, `DIRECT_TOOL_DEFINITIONS`, and `getToolSchemaVariants` are the single public sources for identities, contracts, and variants. Each input schema owns its branch relations and diagnostics. Core input schemas preserve accepted caller values; they may add documented defaults or reject invalid input, but never clamp or silently discard it. The canonical internal specifications retain output schemas for native contract generation, result validation, and contract fingerprinting. They are not part of the public `/schema` export. Execution packages remain responsible for producing and validating result envelopes. This package contains no tool runners, CLI command registry, or skill bundle. `clasify` exposes JEV's `noul`, `choice`, `score` and experimental `box` questions, preserving keyed answers, probabilities, legends, model and usage. Each evaluation row in `{queries:[...]}` supplies keyed `questions` and exactly one of held `state` or an unread text `source`: a `localFetch` or `ghGetFileContent` reference with `ranges` or `fullContent:true`, or an HTTPS `url`. Native captures the complete selection internally and returns a read suggestion in the `hints` string array, pinned to the same snapshot or commit, never the body. A suggestion names the tool and its JSON input. An object in `state` remains data. `mainGoal` and `reasoning` remain metadata. The section-research contract adds `{operation:"sections",resources,questions}` for one to 25 named local/GitHub/HTTPS text resources and one shared set of one to 25 typed questions. Whole-source and image evaluation remain available. Section results group keyed outcomes under each resource, retaining source version, a structured executable `resources..read` reference, exact target/context coordinates and cumulative coverage. Every settled section carries every question outcome: `answered`, `error`, `unsupported` or `unassessed`. A Choice label such as "unknown" remains an answered value; no universal threshold changes its type. Section answers omit the repeated type and Score legend: both come from the shared questions. Each answer retains its value, confidence and full distribution. `next.nextSectionPage` resumes assessment with an opaque `assessment` token; `responsePagination.next` reads immutable settled output without inference. The frozen work plan binds the resources, questions, model and access context. Each settled section is emitted once across assessment batches; display fragments use `rowPart`, with shared questions on the first fragment. Coverage is cumulative and must not be added across batches. A terminal row can retain its resources and coverage alongside a canonical `error`. Development status: the section contract is implemented; runtime integration and end-to-end validation are pending. These are contract requirements, not measured quality or token savings. For unread images, `assets` maps opaque placeholders used in state or question strings to `{type:"image",source:...}`. Image origins reuse local/GitHub reader identity fields or an HTTPS URL; they take no text selectors. Native supplies PNG/JPEG bytes and the provider's experimental image header. Results expose image dimensions, digest, pinned origin and an expiring inspection path, never base64. Box answers retain normalized coordinates and nullable confidence. Octocode permits up to eight images, 8 MiB each and 16 MiB total, bounded to 256–1,568 pixels per edge and 78,400–2,458,624 pixels per image. A separate `{operation:"models"}` row lists the account's provider models. `longContext:true` opts into the provider's experimental long-context header and raises Octocode's complete-state bound from 32,000 to 256,000 characters; the provider may still reject a request. These are Octocode resource bounds, not provider context guarantees. Inspect `octocode schema clasify --view query` for the full contract, including optional/null provider question fields. Answers are bounded judgments, not proof: read the deciding lines before a source claim. A failed or oversized row returns an error, never a negative answer. Exact reads and AST/LSP identity checks remain the better starting point when the target or binding is already known. ## Consumers This package only authors contracts. The octocode monorepo's `@octocodeai/config` is the single generator: after changing a schema here, build this package and run `yarn contracts:regen` in the octocode repo. That writes `packages/octocode-config/contract/` (the native enforcement contract, fixtures, provenance, and generated Rust types) plus the TypeScript tool types exported from `@octocodeai/config/schema`; `octocode-native` embeds `contract/` at build time. Name a vocabulary shared across tools with `.meta({ title: "Name" })` so it becomes one generated type everywhere. The build also writes `dist/public-catalog.json` and one exact agent-facing contract per tool under `dist/schema-templates/`. Use those generated files for schema review and size measurement; they include the full public input/query contract and intentionally exclude output schemas, matching MCP and CLI discovery. ## Package discovery and lookup `artifactSearch` finds packages by name or discovery terms and returns registry metadata, including upstream source links when available. For example: ```json { "queries": [{ "ecosystem": "npm", "packageName": "@types/node" }] } ``` Use `octocode schema artifactSearch --view query` for supported ecosystems, version rules, pagination, and registry options. PyPI supports exact lookup, not keyword discovery; `registryUrl` applies only to npm. Registry metadata is a lead to source code, not proof of implementation behavior, and `artifactSearch` does not install packages. --- _Source: https://npm.io/package/@octocodeai/octocode-core · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._