UltraKit

UltraKit is a scaffolding and maintenance CLI for OpenCode projects. It generates and upgrades a complete OpenCode-ready project structure: agents, slash commands, skills, memory files, tools, plugins, validation scripts, and configuration.

Think of it as create-react-app for OpenCode projects — it bootstraps the environment, validates it, and keeps it maintainable over time.

What UltraKit Is

UltraKit is a project scaffolding and maintenance CLI. It:

• Generates a validated .opencode/ template with agents, commands, skills, tools, plugins
• Initializes .beads/ for multi-agent task coordination
• Validates project configuration (docs-drift, command-doc, skill-lint)
• Upgrades templates to latest repository state via uk upgrade
• Manages project health via uk doctor and uk status

What UltraKit Is Not

UltraKit is not primarily a runtime orchestration plugin.

Runtime plugins such as Oh My OpenAgent enhance what happens during an active OpenCode coding session: background agents, model routing, specialized runtime roles, and live multi-agent execution.

UltraKit operates one layer earlier and one layer longer: it creates, standardizes, upgrades, and governs the project structure those sessions run inside.

Long-Term Direction

UltraKit will be developed continuously across four connected layers:

1. Personal AI dev environment — a dogfooded setup for real daily work.
2. Reusable starter kit — a reliable template for new OpenCode projects.
3. Packaged tool — an installable CLI with validation, upgrades, and guided setup.
4. Agent operating-system layer — a project substrate for agents, memory, workflows, skills, verification, and compounding improvements.

The goal is not only to help agents code, but to help OpenCode projects remember, coordinate, verify, and improve over time.

What This Template Includes

• Beads-first lifecycle: /create -> /plan (optional) -> /ship (or /lfg for the full loop)
• Custom agents installed to .opencode/agent/ (template source: dist/template/opencode/agent/)
• Slash commands installed to .opencode/command/ (template source: dist/template/opencode/command/)
• Skills installed to .opencode/skill/ (template source: dist/template/opencode/skill/)
• Custom tools installed to .opencode/tool/ (template source: dist/template/opencode/tool/)
• Plugins installed to .opencode/plugin/ (template source: dist/template/opencode/plugin/)

Quick Start

# Scaffold or initialize
npx ultrakit init

# Or in this repository during development
npm install
npm run dev -- --help

Optional: Upstream Superpowers

UltraKit already includes a curated workflow skill library, including many skills that overlap with the upstream obra/superpowers project. Superpowers is therefore not installed by default: its plugin adds overlapping skills and injects its own bootstrap instructions into OpenCode sessions.

If you explicitly want the upstream Superpowers plugin in a newly initialized project, run:

npx ultrakit init --with-superpowers

This appends the pinned OpenCode plugin spec to the generated .opencode/opencode.json:

superpowers@git+https://github.com/obra/superpowers.git#v5.1.0

For an existing project, add the same pinned entry manually to the plugin array in .opencode/opencode.json. Treat it as opt-in remote plugin code loaded by OpenCode, and update the pinned tag deliberately during maintenance.

Honcho Persistent Memory (Default)

Honcho provides persistent memory for OpenCode agents — decisions, preferences, and context that survive across sessions. It's included by default in all UltraKit-generated projects because the plugin entry is just a package name (no secrets) and Honcho is inert until you configure it.

For This Repo (Current Workspace)

This repo now has @honcho-ai/opencode-honcho in .opencode/opencode.json. To activate:

1. Restart OpenCode (required for plugin registration)
2. Run /honcho:setup — choose Honcho Cloud (default), paste your API key
3. Run /honcho:status to verify connectivity

Recommended settings for this repo:

• Recall mode: hybrid (context injection + tool access)
• Session strategy: per-repo (one session for the whole repo)

For New Projects

Honcho is now default — no flag needed:

npx ultrakit init

This produces .opencode/opencode.json with @honcho-ai/opencode-honcho already in the plugin array. After init, run /honcho:setup inside an OpenCode session to configure your API key (stored in ~/.honcho/config.json, never in project files). Use /honcho:status to verify the connection.

Integration Paths

| Path | When to Use | | ------------------------------------- | ---------------------------------------------------------- | | OpenCode Plugin (default) | Agent memory in coding sessions | | CLI (honcho-cli) | Diagnostics and workspace inspection | | TypeScript SDK (@honcho-ai/sdk) | Custom app-level integration (not needed for agent memory) | | MCP Server | Advanced manual tool access |

Important Notes

• Never commit API keys. Use ~/.honcho/config.json or environment variables.
• Self-hosted or Docker Honcho requires Python 3.10+, Postgres with pgvector, and an LLM provider. Set baseUrl in ~/.honcho/config.json to your deployment endpoint.
• The npm package honcho is unrelated — always use @honcho-ai/opencode-honcho for the plugin.

Core Slash Command Workflow

Use these inside OpenCode:

1. /create <description> — create bead and PRD
2. /plan <bead-id> — optionally create a detailed implementation plan
3. /ship <bead-id> — implement, verify, review, close

Available Slash Commands (Template)

• /compound
• /create
• /cleanup
• /curate
• /design
• /explore
• /handoff
• /health
• /ideate
• /init
• /init-context
• /init-deep
• /init-user
• /iterate
• /lfg
• /plan
• /pr
• /pr-cleanup
• /research
• /resume
• /review
• /review-codebase — deprecated compatibility alias; use /review
• /ship
• /status
• /team
• /ui-review
• /ui-slop-check
• /verify

CLI Command Surface (uk)

The packaged CLI commands are:

• uk init
• uk agent <list|create|view|remove>
• uk command <list|create|show|delete>
• uk config [action]
• uk doctor
• uk status
• uk upgrade
• uk patch [action]
• uk completion [shell]
• uk tui

See CLI.md for command usage details.

Repository Layout

src/                  # CLI implementation
dist/template/opencode/    # Canonical template source (tracked in git)
.beads/               # Task tracking database and artifacts
dist/                 # Build output (generated)

Development

npm run typecheck
npm run lint
npm run test
npm run build

Release Process

Npm is the source of truth for the currently published version:

npm view @ultrakit/ultrakit version dist-tags time --json

Future releases should be prepared from a clean, up-to-date main branch:

npm run release --bump=patch

The local release script prepares the version bump, release commit, and Git tag only. It does not publish to npm. The GitHub Actions release workflow publishes from pushed v* tags after verifying that the tag, package.json, template version, built CLI version, and packed artifact metadata all agree.

Before cutting a release, confirm the working tree is clean and all intended release artifacts are tracked:

git status --short
npm pack --dry-run --json

Known provenance caveat: npm 0.0.12 is the published latest version, but its gitHead/v0.0.12 tag points at source that still declares 0.0.11. Do not rewrite that immutable npm release; use the hardened release flow above for subsequent versions.

Documentation

• CLI.md - uk command reference
• dist/template/opencode/README.md - packaged OpenCode configuration guide
• dist/template/opencode/AGENTS.md - packaged agent rules and operating constraints
• dist/template/opencode/plugin/README.md - plugin architecture and tooling

Notes

• Do not edit dist/index.js or dist/index.d.ts directly; they are generated by npm run build. dist/template/opencode/ is the canonical template source — edit there directly.
• This repository targets Node.js runtime compatibility (engines.node >= 20.19.0).