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.

Architecture

UltraKit is a project scaffolding and maintenance CLI that operates one layer earlier and one layer longer than runtime plugins. It creates, standardizes, upgrades, and governs the project structure that OpenCode sessions run inside.

The template ships 15 agents, 28 slash commands, 115 skills, 2 custom tools, and 7 plugins — all installed to .opencode/ by uk init.

Architecture: The .opencode/ directory is the project substrate. Agents coordinate work, commands define workflows, skills provide reusable procedures, tools offer MCP integrations, and plugins extend the runtime.

flowchart TD
    accTitle: UltraKit Template Architecture
    accDescr: The .opencode directory contains agent, command, skill, tool, plugin, memory, context, and dcp-prompts subdirectories with their respective counts
    OC[".opencode/"]
    AG["agent/ 15"]
    CM["command/ 28"]
    SK["skill/ 115"]
    TL["tool/ 2"]
    PL["plugin/ 7"]
    MM["memory/"]
    CX["context/"]
    DP["dcp-prompts/"]
    OC --> AG
    OC --> CM
    OC --> SK
    OC --> TL
    OC --> PL
    OC --> MM
    OC --> CX
    OC --> DP

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.

Agent Hierarchy

Agent tiers: Primary agents initiate and coordinate. Moderate agents execute assigned tasks. Minimal agents are read-only investigators.

flowchart TD
    accTitle: Agent Autonomy Hierarchy
    accDescr: Three tiers of agent autonomy. Primary: build, plan. Moderate: compaction, general, painter. Minimal: 10 read-only specialists.
    subgraph Primary
        B["build"]
        P["plan"]
    end
    subgraph Moderate
        CO["compaction"]
        G["general"]
        PA["painter"]
    end
    subgraph Minimal
        DA["daedalus"]
        DB["debugger"]
        EX["explore"]
        ME["metis"]
        MO["momus"]
        OR["oracle"]
        RE["review"]
        SC["scout"]
        VE["verify"]
        VI["vision"]
    end

What UltraKit Is

• 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 creates, standardizes, upgrades, and governs the project structure those sessions run inside.

Workflow Lifecycle

Workflow: Start with ideation, create a tracked bead, research, optionally plan, then ship. The full loop chains all phases autonomously.

flowchart LR
    accTitle: Slash Command Workflow Lifecycle
    accDescr: The workflow starts with ideate, flows through create, research, optionally plan, then ship, compound, pr, and cleanup. LFG chains all phases in one command.
    I["ideate"] --> C["create"]
    C --> R["research"]
    R --> P["plan"]
    C --> S["ship"]
    P --> S
    S --> CO["compound"]
    CO --> PR["pr"]
    PR --> CL["cleanup"]
    LFG["lfg"] -.->|"chains all phases"| C

• /ideate <idea> — structured ideation with alternatives before committing
• /create <description> — create bead, write PRD, set up workspace
• /research <bead-id> — gather codebase and external context before planning
• /plan <bead-id> — detailed implementation plan (optional)
• /ship <bead-id> — implement, verify, review
• /compound <bead-id> — extract and persist learnings
• /pr <bead-id> — prepare GitHub PR
• /cleanup <bead-id> — post-merge cleanup, close bead
• /lfg <bead-id> — full autonomous chain: Research → Plan → Work → Review → Compound
• /ultra <idea> — autonomous pipeline: ideate, create, ship, and PR in one command

Quick Start

# Scaffold or initialize
npx ultrakit init

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

TPS Meter (Auto-Installed)

UltraKit auto-installs the opencode-tps-meter during uk init, which adds a tokens-per-second display to the OpenCode TUI footer. This provides real-time visibility into model response speed.

Prerequisites: bun, zsh, git, curl

Version compatibility: The TPS meter is tested with OpenCode ≤1.4.1. If your OpenCode version is newer, the install is skipped with a warning — you can install manually later when compatibility is confirmed.

Manual install:

npx -y @guard22/[email protected] install

Uninstall:

npx -y @guard22/[email protected] uninstall

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.

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 was published from a dirty workspace, so 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. npm 0.0.13 was published from a validated detached v0.0.13 worktree after GitHub Actions was unavailable.

Direct npm publish fallback is allowed only when GitHub Actions is unavailable and the user explicitly approves it. Publish from a clean detached release-tag worktree, not from the main repo worktree. Check the active npm config inside that worktree with npm config get userconfig, npm config get registry, and npm whoami --registry=https://registry.npmjs.org/; repo-local .npmrc files can shadow /root/.npmrc and cause false E401 failures. Redact _authToken values from any output.

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).