Kujo Pi

An opt-in Pi package that gives developers a quiet, reviewable bridge into the Kujo ecosystem.

Kujo Pi 1.0 is the stable line. New users should start with the Pi onboarding guide. The compatibility policy, migration guide, support policy, changelog, and v1 release standard define its guarantees. For copy-ready examples for every capability, see Capability examples.

To route Pi model requests through the local Watchdog observability proxy, see Route Pi model traffic through Watchdog. To add opt-in agent, turn, tool, shell-request, and session telemetry, see Send Pi lifecycle telemetry to Watchdog.

Kujo Pi does not replace Pi's workflow. It adds Kujo only when it is useful: repository intelligence, scoped context, deterministic checks, workflow orchestration, approvals, receipts, telemetry, retrieval, and guarded MCP generation.

Kujo Pi is designed for production use within a clear boundary: it is a local client integration, not a universal enterprise platform. Enterprise readiness also depends on the Pi host, the installed Kujo tools, service policy, release controls, and organization-specific testing. kujo_doctor, project-trust checks, explicit entrypoint configuration, and approval gates make those dependencies visible.

The default test suite is offline. It covers supported Node versions, the packed extension running through a real Pi RPC host, package contents, signed registry integrity, service failure fixtures, performance budgets, path and origin containment, bounded I/O, project trust, approval binding, entrypoint provenance, and release-workflow invariants.

Install

Install the current stable release from npm:

pi install npm:@kujolang/kujo-pi

Alternatively, install directly from GitHub. Pin a reviewed full commit for team and CI use:

pi install -l git:github.com/kujolang/kujo-pi@<full-commit-sha>

-l keeps the package in the project-local .pi/settings.json. This is the recommended team-sharing mode. Use @main only when you intentionally want the latest unreleased code. Global installation is also supported:

pi install git:github.com/kujolang/kujo-pi@<full-commit-sha>

The extension stays quiet at startup. On macOS/Linux, explicitly preview and approve a private, versioned Kujo/Kennel toolchain with /kujo setup plan review and /kujo setup install review. No ecosystem source checkout is required. Existing KUJO_BIN and integration overrides remain supported. Setup never changes shell profiles or unrelated Pi settings.

First use

Start Pi in a trusted Git repository with a working-tree change:

/kujo setup review
/kujo setup plan review
/kujo setup install review
/kujo demo

Review the exact versions, commands, network access and write locations before confirming installation. /kujo demo reports the actual change footprint without credentials or a model call. To prepare context instead, install and enable the understand pack. /kujo setup is read-only; installation requires the explicit install action and interactive approval. Headless users can use the digest-approved setup CLI.

Pi core supports macOS, Linux and Windows. Managed Kennel setup supports macOS/Linux; Windows users can run those tools in WSL. See the platform and recovery details.

If automatic registry discovery is not available, configure the Kujo workflow you want to use. For example:

export KUJO_SCOUT_ENTRY="/absolute/path/to/scout/scout.kujo"
export KUJO_SCENT_ENTRY="/absolute/path/to/scent/scent.kujo"

For a standard Kujo ecosystem checkout, one root replaces the individual entrypoint variables:

export KUJO_ECOSYSTEM_ROOT="/absolute/path/to/kujo-repos"

Then start Pi in a trusted repository and ask naturally:

Use Kujo Scout to understand this repository, then prepare a scoped context pack for the task we discussed.

Useful commands and prompts:

/kujo
/kujo setup
/kujo packs
/kujo list
/kujo active
/kujo enable understand
/kujo init
/kujo-finish
Use kujo_tools to see the available integrations.
Enable kujo_changebucket and review the current changes.

The package begins with optional and service-backed integrations inactive. A project must be trusted in Pi before these tools can be enabled or run. Ask Pi to enable a capability when you need it, or use /kujo enable understand. Activation is stored in the Pi session and restored when that session is reloaded or its tree is navigated.

/kujo init creates only .kujo/pi/README.md, refuses to overwrite it, and is useful for making project-local Kujo artifacts visible to a team.

Included capabilities

| Capability | Default | Purpose | Side effects | |---|---:|---|---| | kujo_tools | active | Discover and enable integrations | Session-only tool activation; optional activation requires project trust | | kujo_doctor | active | Check local tools, project trust, entrypoints, and network configuration | Version probes in trusted projects only | | kujo_status | active | Check Kujo installation | Read-only | | kujo_check | active | Validate .kujo source | Read-only | | kujo_scout | opt-in | Map repository structure, dependencies, routes, and risks | Writes Scout output when configured | | kujo_scent | opt-in | Prepare scoped context with provenance and redaction metadata | Dry-run by default | | kujo_review_changes | opt-in | Generate a PatchBrief handoff | Writes a review artifact | | kujo_changebucket | opt-in | Measure change footprint and blast radius | Writes a report | | kujo_shipcheck | opt-in + approval | Run release-readiness checks | Executes project checks | | kujo_mcp_make | opt-in + approval | Generate a guarded repo-specific MCP server | Writes scaffold and artifacts | | kujo_dispatch_run | opt-in + approval | Run a resumable Dispatch workflow | Executes workflow and writes state | | kujo_agents_smoke | opt-in + approval | Run deterministic Agents SDK fixtures | Executes fixture suite | | kujo_runledger | opt-in | Start or finish a RunLedger receipt | Writes local ledger data | | kujo_watchdog | opt-in | Read configured Watchdog health/telemetry | Network only when configured | | kujo_leash_approval | opt-in + approval | Send an approval event to Leash | Network only when configured | | kujo_rag_query | opt-in | Query a local RAG index with citations | Read-only query | | kujo_ability_list | opt-in | Discover principal-visible Kujo Abilities | Configured-origin read | | kujo_ability_call | opt-in + approval | Run a canonical Ability through its application gateway | Server-declared effects |

Integration configuration

The package uses installed Kujo tools when available. Set entrypoint variables when a tool is not installed as a standalone binary:

| Variable | Meaning | |---|---| | KUJO_BIN | Kujo runtime executable; default kujo | | KUJO_ECOSYSTEM_ROOT | Optional ecosystem checkout discovered through the signed integration registry | | KUJO_INTEGRATION_REGISTRY / KUJO_INTEGRATION_REGISTRY_SIGNATURE / KUJO_INTEGRATION_REGISTRY_PUBLIC_KEY | Optional absolute paths for an operator-trusted registry bundle | | KUJO_SCOUT_BIN / KUJO_SCOUT_ENTRY | Scout binary, or required absolute .kujo entrypoint when no binary is configured | | KUJO_SCENT_BIN / KUJO_SCENT_ENTRY | Scent binary, or required absolute .kujo entrypoint when no binary is configured | | KUJO_PATCHBRIEF_BIN / KUJO_PATCHBRIEF_ENTRY | PatchBrief executable or absolute entrypoint override | | KUJO_CHANGEBUCKET_BIN / KUJO_CHANGEBUCKET_ENTRY | ChangeBucket executable or absolute entrypoint override | | KUJO_SHIPCHECK_BIN / KUJO_SHIPCHECK_ENTRY | ShipCheck executable or absolute entrypoint override | | KUJO_MCP_ENTRY | Required absolute MCP mcp.kujo path | | KUJO_DISPATCH_ENTRY | Required absolute Dispatch dispatch.kujo path | | KUJO_AGENTS_SMOKE_ENTRY | Required absolute Agents SDK fixture runner path | | KUJO_RAG_ENTRY | Required absolute RAG main.kujo path | | KUJO_RUNLEDGER_BIN / KUJO_RUNLEDGER_ENTRY | RunLedger executable or absolute entrypoint override | | KUJO_WATCHDOG_URL | Optional local Watchdog base URL | | KUJO_ABILITY_GATEWAY_URL | Optional local or HTTPS application Ability gateway | | KUJO_ABILITY_GATEWAY_TOKEN / KUJO_ABILITY_GATEWAY_AUDIENCE | Least-privilege bearer token and optional audience header | | KUJO_WATCHDOG_TOKEN / KUJO_WATCHDOG_AUDIENCE | Optional Watchdog bearer token and audience header | | KUJO_WATCHDOG_TELEMETRY | Set to metadata to enable the trusted-project lifecycle bridge | | KUJO_WATCHDOG_PROXY_PROVIDER | Pi provider ID eligible for Watchdog correlation headers; default kujo-watchdog | | KUJO_PI_TELEMETRY_SPOOL_DIR | Optional durable telemetry spool root | | KUJO_PI_TELEMETRY_SPOOL_MAX_BYTES / KUJO_PI_TELEMETRY_SPOOL_MAX_FILES | Bounded spool limits | | KUJO_PI_TELEMETRY_TIMEOUT_MS | Per-delivery timeout; default 2000 | | KUJO_LEASH_URL | Optional Leash daemon base URL | | KUJO_LEASH_TOKEN | Leash bearer token; never logged | | KUJO_LEASH_AUDIENCE | Optional Leash audience header | | KUJO_PI_MIN_KUJO_VERSION | Optional minimum Kujo version for Doctor compatibility reporting | | KUJO_PI_RECEIPTS | Set to 1 to persist redacted per-call receipts in the Pi session |

Example for a local Kujo checkout:

export KUJO_BIN="$HOME/src/kujo/target/release/kujo"
export KUJO_SCOUT_ENTRY="$HOME/src/scout/scout.kujo"
export KUJO_SCENT_ENTRY="$HOME/src/scent/scent.kujo"
export KUJO_MCP_ENTRY="$HOME/src/mcp/mcp.kujo"
export KUJO_DISPATCH_ENTRY="$HOME/src/dispatch/dispatch.kujo"
export KUJO_AGENTS_SMOKE_ENTRY="$HOME/src/agents-sdk/examples/examples_smoke_runner.kujo"
export KUJO_RAG_ENTRY="$HOME/src/rag/main.kujo"

Kujo Pi canonicalizes configured entrypoints and refuses missing, relative, or non-file paths. kujo_doctor reports not configured when an integration still needs setup.

The packaged signed registry lets Doctor discover and checksum a compatible ecosystem checkout. Every tool result, approval binding, and optional receipt follows the versioned Kujo Pi contracts.

Safety model

• Optional integrations are inactive until enabled.
• Every subprocess, network call, and project write requires a project that Pi reports as trusted.
• Release checks, MCP generation, Dispatch, Agents SDK runs, and Leash delivery require explicit approval. Interactive sessions always show the approval UI; confirm: true is accepted only in trusted headless sessions.
• Kujo workflow entrypoints must be absolute, operator-configured files. Repository-local fallback names are not executed.
• User paths are resolved inside Pi's current workspace and passed as argument-array values, never interpolated into shell strings.
• Command output is bounded before it is returned to the model; streamed UTF-8 is decoded across chunks and truncation is explicitly marked. Commands are noninteractive (stdin is closed).
• Configured service tokens are read from environment variables and are not added to tool results by Kujo Pi. External commands and services control their returned content.
• Receipts are disabled by default; when enabled, they record only operation, workspace, status, exit code, duration, and timestamp.
• Network integrations are disabled unless their URL is explicitly configured; Leash also requires a token, while Watchdog credentials are optional.
• Lifecycle telemetry additionally requires KUJO_WATCHDOG_TELEMETRY=metadata and a trusted project. Its local spool contains only allowlisted metadata, uses restrictive file modes, and never stores service credentials.
• Watchdog correlation headers are added only when the active Pi provider exactly matches KUJO_WATCHDOG_PROXY_PROVIDER; direct providers never receive them.
• Configured HTTP integrations are restricted to the configured origin; user-supplied paths cannot redirect requests to another host.
• Every network attempt has its own timeout, including calls that also carry a caller cancellation signal.
• Existing symlink targets are resolved before a workspace path is accepted, preventing repository-local links from escaping the workspace.
• Kujo Pi does not claim to enforce Kujo or Pi permissions; the host, Kujo runtime, and configured external services remain authoritative.

Pi extensions run with the user's system permissions. Review this source before installing it. See SECURITY.md for the threat model and reporting process.

Architecture

Pi session
   │
   ├── kujo_tools ── discovers and enables capabilities
   ├── repository tools ── check / Scout / Scent / PatchBrief / RAG
   ├── approved tools ── ShipCheck / MCP / Dispatch / Agents SDK
   ├── local receipts ── RunLedger
   └── opt-in network edges ── Watchdog / Leash
          ├── Watchdog proxy ── model requests and provider telemetry
          ├── metadata bridge ── agent / turn / tool / shell lifecycle
          └── Kujo CLI, MCP, and workflow contracts

Runtime implementation lives in src/. extensions/kujo.ts is intentionally a two-line compatibility entrypoint required by Pi's package manifest. Skills, prompts, documentation, tests, and workflow configuration stay in their conventional top-level directories.

Development

npm ci --ignore-scripts
npm run typecheck
npm test

The test suite is offline and validates the package manifest, TypeScript extension contract, source layout, documentation links, path containment, trusted entrypoint selection, approval and project-trust gates, output bounds, network timeouts, and release workflow.

Post-1.0 hardening and expansion priorities are documented in the roadmap. The evidence required for a production release is documented in the production-readiness standard.

Recommended local and remote service profiles are documented in docs/service-profiles.md. The Kujo CLI and service checks are available with KUJO_PI_LIVE=1 npm run test:live; add KUJO_PI_ECOSYSTEM_ROOT=/path/to/kujo-repos to exercise the full local adapter matrix. Live checks never run in the default offline test suite.

Scope boundary

Kujo Pi is a client integration layer. It does not duplicate Kujo runtime logic, provider adapters, workflow engines, MCP authorization, mobile approval policy, or RAG storage. Those remain in the canonical Kujo repositories:

• Kujo Skills
• Agents SDK
• Dispatch
• MCP
• RAG
• RunLedger
• Watchdog
• Leash

License

MIT