UKit

UKit installs a project-local AI workspace (.claude/, adapters, docs, and index helpers) so your team can work with Claude Code, OpenAI Codex, and omp (Oh My Pi) from the same repo setup.

Install

1. Install the UKit CLI globally:

   npm install -g @ngockhoale/ukit

2. Open any project root in the terminal and run:

   ukit install

The same ukit install command handles both first-time setup and refreshes. If UKit changes, your templates change, or a teammate needs to re-apply the workspace, rerun ukit install.

After install

For normal team usage, ukit install is the only UKit command anyone should need to remember:

• open your AI tool
• describe the task in natural language
• let the workspace instructions route the flow

Fill in the generated docs baseline (docs/PROJECT.md, docs/MEMORY.md, docs/AI_HANDOFF/, docs/WORKLOG.md), then work in natural language. Do not onboard the team around ukit doctor, ukit diff, ukit uninstall, or ukit index ... — those remain maintainer/debug workflows, not the default human path.

What ukit install creates

Core workspace

• .claude/skills/ — canonical skills
• .claude/agents/ — specialist agents
• .claude/hooks/ — tool hooks
• CLAUDE.md — Claude Code instructions
• AGENTS.md — shared instructions for AGENTS-compatible tools

Adapters

• .codex/settings.json + .codex/settings.local.json — Codex config
• .omp/AGENTS.md — thin @../AGENTS.md import so omp reads the shared instructions
• .omp/RULES.md — sticky hard rules for omp sessions
• .omp/config.yml — omp model roles, tool approval, and bash patterns
• .omp/agents/ — the six shared agents in omp's task-agent format
• .omp/hooks/pre/ukit-bridge.js — bridges omp events onto the existing .claude/hooks/*.sh

Project support files

• .claude/ukit/.ukit/ — installer manifests, metadata, backups
• .ukit/ — hidden shared runtime storage for config, cache, and cross-agent memory
• docs/ — PROJECT / MEMORY / AI_HANDOFF / WORKLOG baseline
• PROJECT_IMPORTANT.md — your project-owner instruction file (see below)

PROJECT_IMPORTANT.md — project-owner instructions

ukit install seeds a root PROJECT_IMPORTANT.md once. After that the file is yours: UKit never rewrites, merges, formats, or deletes it — edits survive every ukit install rerun byte-for-byte, and uninstall backs it up to a sibling PROJECT_IMPORTANT.md.ukit-backup[.n] file instead of deleting it.

Put your non-negotiable project rules there. On each session start your AI tool receives its contents as advisory project-owner context. Keep the file at or below 6,000 Unicode code points — anything past that is truncated with an explicit warning. Do not put credentials or secrets in it: a fail-closed sensitive-value scan runs before injection and blocks anything that looks like a key or token.

Shared runtime

UKit installs a hidden shared local runtime at .ukit/ for production-oriented state that survives across agent sessions:

• .ukit/storage/config.json — runtime defaults for compact/router/memory/validation/subagent hints
• .ukit/storage/cache/ — reusable prompt-cache, compact history, and output summaries
• .ukit/storage/memory/ — cross-agent local memory
• .ukit/storage/backups/ — rollback bytes for risky Safe Patch Protocol edits

When long sessions approach the compact threshold, UKit compacts only safe-zone history/noise while preserving the active task, rules, decisions, and current code focus. If an older repo still has a visible legacy ukit/ runtime folder, rerunning ukit install migrates the shared runtime into hidden .ukit/ when the target paths are free.

Supported tools

| Tool | Instructions | Skills | Config | |------|-------------|--------|--------| | Claude Code | CLAUDE.md | .claude/skills/ (canonical) | .claude/settings.json | | OpenAI Codex | AGENTS.md | .claude/skills/ (referenced) | .codex/settings.json, .codex/settings.local.json, .codex/README.md | | omp (Oh My Pi) | .omp/AGENTS.md (imports AGENTS.md) | .claude/skills/ (read via omp's claude provider — no symlink) | .omp/config.yml, .omp/RULES.md, .omp/README.md |

All supported tools share the same SKILL.md ecosystem so the workspace is authored once and reused everywhere.

Maintainer docs

Maintainer internals live in dedicated docs — linked here, not duplicated:

• docs/CONTEXT_BUDGET.md — retuning the context budget (three-number edit)
• docs/UKIT_CODEV_PRINCIPLES.md — CoDev working principles
• docs/RELEASE_CHECKLIST.md — release steps

Maintainer/debug commands (advanced workflows, not team onboarding):

• ukit diff — preview file changes before install
• ukit doctor — validate UKit state and docs baseline
• ukit uninstall — remove UKit-managed assets
• ukit status — inspect shared UKit runtime state
• ukit memory ... — inspect/export/forget shared memory items
• ukit update — upgrade the global UKit CLI to the latest published version
• ukit index ... — run repo indexing/query/triage tools directly
• ukit telemetry ... — inspect the opt-in local flight recorder (segments, digests, Documents/UKit Support export) — see docs/OBSERVABILITY.md
• ukit build index — alias for ukit index build

Development

For maintainers evolving UKit itself, run the test suite from the repo root:

yarn test

Repo-level index scripts:

• yarn index:build
• yarn index:refresh
• yarn index:query -- "<error|symbol|path>"
• yarn bug:triage -- "<error signature>"