# @octocodeai/agent-contracts > Canonical Octocode prompts, protocol types, entities, paths, permissions, and local SQLite plumbing shared across hosts. Latest version **0.1.0** (published 2026-09-06) · MIT license · 0 weekly downloads ## Install ```sh npm install @octocodeai/agent-contracts pnpm add @octocodeai/agent-contracts yarn add @octocodeai/agent-contracts bun add @octocodeai/agent-contracts ``` ## Health **Score 70/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score. Warnings: low downloads; pre 1.0. ## Facts | | | |---|---| | Version | 0.1.0 | | Published | 2026-09-06 | | First published | 2026-09-06 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Node | >=22.13.0 | | Dependencies | 2 | | Unpacked size | 186.8 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 4 | | Author | Guy Bary | | Maintainers | bgauryy | | Keywords | octocode, shared, paths, sqlite, sessions, prompts, protocols, agent | ## Links - npm: https://www.npmjs.com/package/@octocodeai/agent-contracts - Repository: https://github.com/bgauryy/octocode-agent - Homepage: https://octocode.ai - Issues: https://github.com/bgauryy/octocode-agent/issues - npm.io page: https://npm.io/package/@octocodeai/agent-contracts ## Dependencies (2) - [yaml](https://npm.io/package/yaml.md) 2.9.0 - [@octocodeai/config](https://npm.io/package/@octocodeai/config.md) 18.0.1 ## Alternatives - [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads - [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads - [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads - [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads - [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads ## Recent versions - 0.1.0 (latest) — 2026-09-06 ## README # Octocode Agent
Octocode Logo **A self-working coding agent — the [Pi](https://github.com/earendil-works/pi) runtime driven by the Octocode harness, with always-on multi-agent coordination.** [![Website](https://img.shields.io/badge/Website-007ACC?style=for-the-badge&logo=link&logoColor=white)](https://octocode.ai) ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)
--- `octocode-agent` is the **agent slice** of the Octocode platform. It packages three layers that turn Pi into an evidence-first, coordinated coding agent: 1. **[`octocode-agent`](packages/octocode-agent)** — the branded launcher CLI. One command, one update path. 2. **[`@octocodeai/pi-extension`](packages/octocode-pi-extension)** — the **harness**: system prompt, MCP research bridge, support tools, skills, and Awareness wiring. 3. **[`@octocodeai/octocode-awareness`](packages/octocode-awareness)** — the **coordination layer**: one package exposing the shared root library + `octocode-awareness` bin for Pi/external interoperability, and the advanced full runtime. > **Pi runs the loop, Octocode owns the tools, Awareness coordinates.** The launcher is thin on purpose — all behavior lives in the harness and coordination packages. --- ## Table of Contents - [Quick Start](#quick-start) - [The Three Layers](#the-three-layers) - [1. octocode-agent — the launcher](#1-octocode-agent--the-launcher) - [2. Pi Extension — the harness](#2-pi-extension--the-harness) - [3. Awareness — CLI + Skill](#3-awareness--cli--skill) - [Tool Ownership](#tool-ownership) - [Terminal Experience](#terminal-experience) - [Extending with MCP Servers and Skills](#extending-with-mcp-servers-and-skills) - [Architecture](#architecture) - [Repository Layout](#repository-layout) - [Developing](#developing) - [How the Pieces Wire Together](#how-the-pieces-wire-together) - [Verified Capabilities](#verified-capabilities) - [Documentation](#documentation) --- ## Quick Start Run the agent — no clone required: ```bash npm install -g octocode-agent octocode-agent # launch the agent (Pi + Octocode harness) octocode-agent --version # launcher, core, and Pi host versions octocode-agent update # self-update the platform (pulls newest core) octocode-agent update core # update @octocodeai/pi-extension in place ``` Or use the harness inside an existing Pi install: ```bash pi install npm:@octocodeai/pi-extension /octocode # dashboard: status, agents, setup, skills, health ``` Authenticate GitHub-backed research once (optional, unlocks private repos + higher rate limits): ```bash npx octocode auth login npx octocode status ``` --- ## The Three Layers ### 1. `octocode-agent` — the launcher The branded entry point. It has a real dependency on `@octocodeai/pi-extension`, so `npm install -g` and `npx` always resolve the pinned harness. It launches Pi in **octocode-first mode** — the Octocode harness leads while Pi's runtime invariants stay underneath. ```bash octocode-agent [agent args...] # launch; Pi-compatible args are mapped by the launcher octocode-agent update # self-update the platform octocode-agent update core # refresh only @octocodeai/pi-extension in this install octocode-agent --agent-help # launcher help (reserved subcommands only) ``` Because the prompt, skills, tools, and memory all live in the core package, nothing is duplicated here — updating the core updates what the agent launches. ➡️ [`packages/octocode-agent`](packages/octocode-agent) · [PI_INTEGRATION.md](packages/octocode-agent/docs/PI_INTEGRATION.md) ### 2. Pi Extension — the harness `@octocodeai/pi-extension` is where the agent gets its brain. Installing it into Pi loads: | Surface | Count | What it is | |---|---:|---| | Octocode research tools via MCP | 15 | GitHub + local + LSP + npm evidence tools through the built-in `octocode` MCP server | | Direct model tools | 16 | Guarded `bash` plus `file`, `web`, `chromeDebug`, `agent`, `callTool`, `skill`, `plan`, `localServer`, `MCPTool`, `askUser`, `memory`, `lock`, `message`, `readMedia`, and `media` | | Bundled skill | 1 | `octocode-awareness`; the rest install on demand via `npx octocode skill --add` | On load it sets `$OCTOCODE_CLI` and `$OCTOCODE_AWARENESS_CLI`, injects the operating-model system prompt, registers edit-safety hooks, arms the session-scoped approval gate, and wires Awareness lifecycle automation. The full TUI layer it adds — banner, footer cockpit, permission levels, an RFC-backed plan gate + a live HTML plan/RFC page — is summarized in [Terminal Experience](#terminal-experience). ```text $OCTOCODE_CLI → node "$OCTOCODE_CLI" $OCTOCODE_AWARENESS_CLI → node "$OCTOCODE_AWARENESS_CLI" --compact ``` > Awareness is deliberately **not** exposed as Pi tools. Agents drive it through the bundled > CLI under the `octocode-awareness` skill; in-process hooks automate file presence, > exclusive-conflict checks, briefings, and finish warnings — one CLI/schema contract, no > duplication. ➡️ [`packages/octocode-pi-extension`](packages/octocode-pi-extension) · [docs](packages/octocode-pi-extension/docs/README.md) · [TOOLS](packages/octocode-pi-extension/docs/TOOLS.md) · [AWARENESS flow](packages/octocode-pi-extension/docs/AWARENESS_AGENT_FLOW.md) ### 3. Awareness — CLI + Skill `@octocodeai/octocode-awareness` gives any coding host one shared coordination contract: - **The shared library** (`@octocodeai/octocode-awareness`) used in-process by Pi. - **The shared CLI bin** (`out/octocode-awareness.js`, exposed at runtime as `$OCTOCODE_AWARENESS_CLI`) — the live-state engine over a local **SQLite** store (zero npm runtime deps, uses built-in `node:sqlite`, requires Node ≥ 22.13). - **The `octocode-awareness` skill** — the external-agent router that points at the shared bin. What it provides: - a live **Plan → Task** queue with reasons, acceptance criteria, paths, and dependencies; - **advisory file presence** — who is editing what and why; - optional **exclusive locks** for sensitive, non-mergeable changes; - durable **memory**, agent-to-agent **messages**, **verification** receipts, and an agent registry with presence counts. ```bash # orient before any repo work (the extension sets $OCTOCODE_AWARENESS_CLI at load) node "$OCTOCODE_AWARENESS_CLI" status --workspace "$PWD" # core lifecycle node "$OCTOCODE_AWARENESS_CLI" work start ... # declare edited paths node "$OCTOCODE_AWARENESS_CLI" task claim ... # claim a ready task node "$OCTOCODE_AWARENESS_CLI" memory recall ... # surface prior verified learning node "$OCTOCODE_AWARENESS_CLI" check mark ... && node "$OCTOCODE_AWARENESS_CLI" check audit ``` Commands: `status · plan · task · lock · work · handoff · agent · message · check · memory · hooks` (run `… schema` for exact shapes). SQLite is canonical; `/.octocode/` is a discovery shelf (authored plan docs), never a second database. No server, no daemon. The same package's full `octocode-awareness` bin adds attend, reflection, projections, sessions, and maintenance in a separate advanced store; it is not the Pi-visible coordination ledger. ➡️ [`packages/octocode-awareness`](packages/octocode-awareness) · [HOW_IT_WORKS](packages/octocode-awareness/docs/HOW_IT_WORKS.md) --- ## Tool Ownership The branded launcher starts Pi with **all native Pi built-ins suppressed** in both launch paths: the SDK session uses `noTools: "builtin"`, and the subprocess uses `--no-builtin-tools`. There is no environment opt-out. The harness then supplies the complete public palette, including its guarded same-name `bash` implementation. | Pi native tool | Octocode route | |---|---| | `read` | `MCPTool` → `localGetFileContent`; local media uses `readMedia` | | `edit`, `write` | `file` with `type:"edit"`, `"write"`, or `"delete"` | | `grep`, `find`, `ls` | `MCPTool` → `localSearchCode`, `localFindFiles`, or `localViewStructure` | | `bash` | Octocode's guarded same-name `bash` tool | Direct Pi users who install only the extension get the same effective palette: the extension removes replaced native names on load and again at session start as a defensive backstop. See [OVERRIDES.md](packages/octocode-pi-extension/docs/OVERRIDES.md) for the exact contract. --- ## Terminal Experience The harness ships a deliberate TUI design system — one palette, one copy source, and motion that always *means* something: | Surface | What you get | |---|---| | **Startup banner** | Branded OCTOCODE card (lens + octopus emblem, white→purple gradient with an animated gloss sweep) rendered once per fresh session as a transcript entry — zero prompt-token cost, re-renders on `/resume`. | | **Footer cockpit** | Context gauge · merged turn timing (`turn 8 · 14s` live, `turns 7 · last 12s` idle) · session uptime · workers/awareness/peer state · effort dial · **always-visible permission mode** · prompt overhead · `branch* ΔN` changed files. `/octocode-footer legend` explains every segment; `compact`/`default`/`full` tune density. | | **Motion language** | *Wave* (footer wordmark ripples) = working · *glow* (breathing ⚠ ✗ ✉ and a ≥90% context gauge) = act on me · *gloss sweep* = brand splash. Deterministic, timer-free, test-pinned so status colors can never become decoration. | | **Approval gate** | Sensitive bash (installs, git mutation, deletes, sudo, publish, system/infra, shell-rc persistence, backtick/`$()` evasion) prompts Yes / No / Always-allow. Session-scoped levels — `strict` / `default` / `relaxed` — via `/octocode-permissions`, a cycle shortcut (default `ctrl+shift+a`), or `OCTOCODE_PERMISSION_LEVEL`. Everything resets on a new session; headless hosts always deny rather than assume consent. | | **Plan workflow** | A gated **research → RFC → approve** flow. `/octocode-plan new ` enters **plan mode** (write tools blocked until approval); the agent orients, then `plan action:clarify` runs a bounded ≤3-question interview whose answers land in a durable **decision log**. Consequential work routes through the `octocode-rfc-generator` skill — and `plan action:propose` **blocks** a consequential plan that has no RFC. Propose sets the checklist *and* asks for sign-off inline (Approve / Reject; free-text = change request, echoed verbatim). `/octocode-plan html` opens a **live local page** — phase timeline, status checklist, mermaid dependency diagram, the **rendered RFC**, the decision log, and a shareable `plan.md` — rewriting on every change while you keep talking in the terminal. | | **Widgets** | Unified below-editor status panel (model → plan → awareness → agents) with a live **phase stepper** (Research → RFC → Approve → Build → Verify), card-styled `askUser` prompts (72-col frame, quiet chrome, recommended-default + pros/cons), filter-preserving select overlays, worker inbox, command palette (default `ctrl+shift+k`). | All copy lives in one content module and all design constants (palette tokens, separators, brand marks, wave/glow painters) in one design module — wording and colors cannot drift between surfaces, and the test suite pins the rules (e.g. only warning/error states may glow). --- ## Extending with MCP Servers and Skills Use **MCP servers** to expose more tools. Use **skills** to teach the agent a reusable workflow. Most integrations only need MCP config — no code change, rebuild, or new skill. MCP server config is read from: | Scope | Paths in precedence order | Loaded when | |---|---|---| | Built-in | pinned local `octocode-mcp` (`npx -y octocode-mcp@latest` fallback) | Always, as server `octocode` | | Global | `~/.pi/mcp.json`; `$OCTOCODE_HOME/agent/mcp.json`; `~/.pi/agent/mcp.json` | When each file exists | | Project | `/.pi/mcp.json`; `/.octocode/agent/mcp.json`; `/.pi/agent/mcp.json` | Only after the project is trusted | A later definition of the same server name wins. Claude Code, Cursor, Codex, `.agents`, and compatibility `.octocode/mcp.json` files are discovery inventory only; copy a trusted stdio entry into an active path before the gateway can run it. Minimal config: ```json { "mcpServers": { "my-server": { "command": "npx", "args": ["-y", "@acme/mcp-server@latest"], "env": {}, "cwd": ".", "timeoutMs": 30000 } } } ``` Inside a session, the agent can also add a trusted server live: ```js MCPTool({queries:[{ reasoning: "Add the trusted external server.", action: "add", server: "my-server", scope: "project", config: { command: "npx", args: ["-y", "@acme/mcp-server@latest"] } }]}) ``` Discovery is automatic: `MCPTool({queries:[{reasoning:"Inspect the server tools.", action:"list",server:"my-server"}]})` lists the server's tools and schemas; `describe` reads one exact tool schema; `call` invokes it. Config files are watched and hot-reloaded, so new tools apply on the next `MCPTool` call. You can also inspect or manage servers from `/octocode-mcp`. Create or install a skill only when the integration needs operating guidance: when to use the tools, how to combine them, validation rules, pitfalls, or a multi-step workflow. For example, a docs-search MCP server can stand alone; a release-management workflow that uses several tools and requires checks is a skill. More detail: [`packages/octocode-pi-extension/docs/TOOLS.md#MCP-Servers`](packages/octocode-pi-extension/docs/TOOLS.md#mcp-servers) and [`packages/octocode-pi-extension/README.md`](packages/octocode-pi-extension/README.md). --- ## Architecture ```mermaid graph TD AGENT["octocode-agent
branded launcher CLI"] PI["Pi runtime
(shell, tool loop, providers)"] EXT["@octocodeai/pi-extension
HARNESS: prompt · MCP research · support tools · skills · hooks"] AW["@octocodeai/octocode-awareness
SHARED COORDINATION: plans/tasks · locks · memory · checks (SQLite)"] SKILL["octocode-awareness skill
external-agent router"] BRAIN["External npm brain (sibling repos)
octocode-tools-core · octocode-engine · @octocodeai/config"] AGENT -- launches --> PI PI -- loads --> EXT EXT -- bundles CLI + skill --> AW EXT -- injects --> SKILL SKILL -- drives --> AW EXT -- consumes --> BRAIN style EXT fill:#1a1a2e,stroke:#e75d2a,color:#fff style AW fill:#12233b,stroke:#4a9,color:#fff ``` **This repo ships the agent, harness, and coordination layers.** The tool-execution brain (`@octocodeai/octocode-tools-core`, `@octocodeai/octocode-engine`, `@octocodeai/octocode-core`), the config loader (`@octocodeai/config`), and the MCP / VS-Code interfaces are published from sibling repos and consumed here as npm dependencies. Never duplicate `getOctocodeHome` or `.env` parsing — always use `@octocodeai/config`. --- ## Repository Layout Yarn 4 workspaces monorepo (`packages/*`), Node ≥ 22 (Awareness runtime needs ≥ 22.13). | Package | npm name | Role | Deep dive | |---|---|---|---| | [`packages/octocode-agent`](packages/octocode-agent) | `octocode-agent` | Branded launcher — one command, one update path. | [docs](packages/octocode-agent/docs/README.md) | | [`packages/octocode-pi-extension`](packages/octocode-pi-extension) | `@octocodeai/pi-extension` | The Pi harness: native tools, CLIs, system prompt, skills, Awareness wiring. | [docs](packages/octocode-pi-extension/docs/README.md) | | [`packages/octocode-awareness`](packages/octocode-awareness) | `@octocodeai/octocode-awareness` | Shared root coordination used by Pi/external agents plus advanced reflection/query/session runtime. Canonical skill source. | [docs](packages/octocode-awareness/docs/README.md) | Agent guides: [`AGENTS.md`](AGENTS.md) (repo) · [`packages/octocode-awareness/AGENTS.md`](packages/octocode-awareness/AGENTS.md) (package). Internals: each package's `ARCHITECTURE.md` where present. --- ## Developing ```bash yarn install # root: fans out to every workspace yarn build # build all packages yarn test # run all test suites yarn lint # lint all yarn typecheck # typecheck all ``` Per-package verification (no root `verify`): ```bash yarn workspace @octocodeai/octocode-awareness verify yarn workspace @octocodeai/pi-extension verify yarn workspace octocode-agent verify ``` Local end-to-end after changing a local package — **rebuild in dependency order**, then exercise the real CLI / harness path (don't claim done from a compile alone): ```bash yarn workspace @octocodeai/octocode-awareness build yarn workspace @octocodeai/pi-extension build yarn workspace octocode-agent build ``` **Conventions.** Plan → TDD → `yarn workspace test` → `yarn lint` → verify. Coverage target ≥ 90% branch (Vitest + v8). No backward-compat by default — refactor freely; add shims only when asked. **Build outputs (do not hand-edit):** `packages/octocode-awareness/out/**` (separate CLI + import-only library/schema API + bundled skills), extension `dist/**`, and any `.agents/skills/**` / `out/skills/**` mirrors. Edit source in `src/**`, `bin/**`, and the canonical skill under `packages/octocode-awareness/skills/octocode-awareness/**`, then rebuild. --- ## How the Pieces Wire Together 1. `octocode-agent` launches **Pi** with `@octocodeai/pi-extension` loaded as the harness. 2. On load the extension sets `$OCTOCODE_CLI` + `$OCTOCODE_AWARENESS_CLI`, registers support tools, injects the operating-model system prompt, and installs edit-safety + Awareness lifecycle hooks. 3. For non-trivial repository work the agent activates the **`octocode-awareness` skill** and runs `status`, then claims work, declares edited files, coordinates with peers, records verified memory, and gates on verification. 4. Research runs through `MCPTool` and the built-in **`octocode` MCP server** (GitHub / local / LSP / npm), backed by the external Rust engine + tools-core packages. **Config is a single source:** all env/config flows through `@octocodeai/config` (`getOctocodeHome`, `propagateOctocodeEnv`, `parseEnv`, `loadOctocoderc`). Skills use the injected `./octocode-config.mjs`; packages import from `@octocodeai/config` or a package-local re-export. --- ## Verified Capabilities Every surface below is exercised end-to-end (live smoke runs + the package test suites), not just compiled. ### Tools | Surface | What's verified | |---|---| | `bash` / `file` | Path-guarded shell plus preflighted edit/write/delete batches with stale/lost-update checks and diffs | | Octocode research (via MCP) | `localSearchCode` · `localViewStructure` · `localGetFileContent` · `localFindFiles` · `localFindDeadCode` · `npmSearch` · `ghSearchCode` · `ghViewRepoStructure` with `next.*` chaining | | `lspGetSemantics` | Live LSP definitions/references/callers with exact file:line anchors | | `web` | Search (provider chain Tavily → Serper → Exa → DuckDuckGo), URL fetch with pagination | | `readMedia` / `media` | Perceives images, video, and audio; authors images/PDFs and transforms media through a separate write boundary | | `chromeDebug` / `agent` | Direct CDP operations plus browser-profile routing and multi-turn worker lifecycle | | `agent` | Typed/custom/browser worker spawn plus inspect/wait/message/steer/abort/kill lifecycle operations | | Awareness (Lite) | `status`, plan/task queue, verification gates (`verify audit`/`mark`), exclusive file locks with the full contention cycle (acquire → conflict → release → re-acquire), agent presence counts | ### Skills Pi owns Awareness instructions in its prompt. External agents can install `octocode-awareness` from the canonical repo-root source [`skills/octocode-awareness`](skills/octocode-awareness). Other workflow skills remain installable with `npx octocode skill --add`. ### Test surface | Package | Suite | |---|---| | `@octocodeai/pi-extension` | Vitest suites across 73 test files (1,200+ tests) — tools, prompts, CDP schemes, subagents, approval gate + permission levels, footer/widgets/animation, the plan/RFC surface (clarify interview, decision log, consequential gate, phase stepper) | | `@octocodeai/octocode-awareness` | Shared SQLite coordination/library/CLI tests, advanced runtime tests, and zero-dependency pack verification | --- ## Documentation | Area | Links | |---|---| | Agent / launcher | [`octocode-agent` docs](packages/octocode-agent/docs/README.md) · [PI_INTEGRATION](packages/octocode-agent/docs/PI_INTEGRATION.md) | | Harness (Pi extension) | [docs index](packages/octocode-pi-extension/docs/README.md) · [TOOLS](packages/octocode-pi-extension/docs/TOOLS.md) · [AWARENESS flow](packages/octocode-pi-extension/docs/AWARENESS_AGENT_FLOW.md) · [REFLECT](packages/octocode-pi-extension/docs/REFLECT.md) · [OVERRIDES](packages/octocode-pi-extension/docs/OVERRIDES.md) | | Awareness | [docs index](packages/octocode-awareness/docs/README.md) · [HOW_IT_WORKS](packages/octocode-awareness/docs/HOW_IT_WORKS.md) · [HOOKS](packages/octocode-awareness/docs/HOOKS.md) · [VERIFY](packages/octocode-awareness/docs/VERIFY.md) · [LOCKS](packages/octocode-awareness/docs/LOCKS.md) · [MEMORY_NAVIGATION](packages/octocode-awareness/docs/MEMORY_NAVIGATION.md) | | Platform | Website **[octocode.ai](https://octocode.ai)** · [Pi](https://github.com/earendil-works/pi) | > The full Octocode platform — MCP server, the `octocode` CLI, the Rust engine, and the VS Code > extension — lives in the sibling [`bgauryy/octocode`](https://github.com/bgauryy/octocode) > monorepo and is consumed here as npm dependencies. --- ## License MIT © [Guy Bary](https://octocode.ai) — see the `license` field in [`package.json`](package.json). --- _Source: https://npm.io/package/@octocodeai/agent-contracts · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._