Setup & Migrate

Get Ultra Claude installed, your machine configured, and your project initialized. This page covers everything from first install to a fully scaffolded project with documentation structure.

Install the plugin

In any Claude Code session:

# Add the marketplace
/plugin marketplace add duniecdawid/ultra-claude-code

# Install the plugin
/plugin install uc@ultra-claude

All skills become available as /uc:* slash commands. Enable auto-updates to stay current:

/plugin marketplace auto-update duniecdawid/ultra-claude-code

Machine setup

/uc:setup

Run this once per machine. Setup configures your environment for Ultra Claude's full capabilities:

1M context window — enables the extended context that agent teams need
Agent teams — enables the experimental agent teams feature for parallel execution
tmux mode (optional) — guides you through four tmux modes: per-project session (recommended), no tmux, per-terminal session (legacy), or custom (user-managed). Installs and configures tmux when needed.
Node.js — required for Ultra Claude scripts (including the tmux layout daemon when tmux is enabled)
VS Code settings (optional) — when VS Code or vscode-server is detected, setup offers recommended client-side settings for the Claude Code extension (printed as merged JSON to paste) and configures mode-aware terminal profiles per the tmux mode. Skipped silently when VS Code isn't installed.
Statusline — per-account usage tracking displayed in the Claude Code status bar
Session hooks — start/end hooks for usage tracking
Agent updates — if the ultraclaude-agent npm package is already installed, setup checks for a newer published version and offers to update it (never installs from scratch)

Setup is idempotent — safe to re-run after updates or if anything changes. It writes a version marker to ~/.claude/ultra/uc-setup.json so other skills can verify your environment is current.

What if setup reports issues?

Setup checks each prerequisite and reports what it finds. If something fails:

tmux mode not configured — setup guides you through choosing a tmux mode. tmux is optional — agent teams work without it.
Node.js not found — setup installs it. Required version: 18+ LTS
Shell config issues — setup adds the required environment variables to your shell config (~/.bashrc or ~/.zshrc)
Screen tearing / flicker — setup offers the Claude Code fullscreen renderer (opt-out, requires Claude Code v2.1.89+), which draws on the alternate screen and is the primary fix for tearing. If tmux is enabled, setup also configures synchronized-output passthrough as a fallback for the classic renderer.

If setup completes but other skills still report missing prerequisites, run /uc:setup again — it will re-verify everything.

Recommended: Ref.tools MCP

Ultra Claude uses Ref.tools to fetch focused external library documentation for agent teams. Without it, agents fall back to web search (50K+ tokens) instead of targeted retrieval (500–5K tokens).

Add the Ref.tools MCP server to your Claude Code configuration:

# In your Claude Code MCP settings
{
  "ref": {
    "command": "npx",
    "args": ["-y", "@anthropic/ref-tools-mcp"]
  }
}

Once configured, the /uc:research skill uses it automatically to fetch current API signatures, deprecation notices, and best practices into the project's knowledge base under documentation/technology/research/.

Project initialization

/uc:migrate

Run this in your target project directory. Migrate handles three project states automatically:

Fresh project (no Ultra Claude files)

For projects that have never used Ultra Claude, migrate:

Scaffolds the documentation/ directory with the canonical structure (technology, product, plans, backlog)
Spawns surveyors to explore your codebase and existing docs
Derives .claude/ultra/ configuration files from findings
Drafts initial architecture documentation from detected patterns
Auto-generates coding standards from your code conventions
Produces testing configuration in documentation/technology/testing/

Legacy project (older Ultra Claude version)

For projects initialized with an older version, migrate detects what's outdated and applies incremental upgrades. It reads the CHANGELOG for migration instructions and applies them in sequence, preserving your existing documentation and configuration.

Current project (already up to date)

If the project is already at the current version, migrate confirms everything is in order and exits.

Migrate never modifies source code. It only creates or moves documentation, configuration, and directory structure. Your codebase is untouched.

What migrate creates

After running migrate on a fresh project, you'll have:

your-project/
├── .claude/
│   └── ultra/                    # Ultra Claude configuration
│       ├── app-context.md        # Project context for AI
│       └── docs-format           # Documentation format (docsify)
├── documentation/
│   ├── README.md                 # Navigable index
│   ├── technology/
│   │   ├── architecture/         # System design docs
│   │   ├── standards/            # Coding conventions
│   │   └── testing/              # Test strategy and config
│   ├── product/
│   │   ├── description/          # Product vision
│   │   └── requirements/         # Formal requirements
│   ├── plans/                    # Feature and fix plans
│   └── backlog/                  # Bugs, questions, ideas, debt
└── CLAUDE.md                     # Project instructions for Claude

Review and refine the generated docs — they're derived from your codebase patterns, not boilerplate. The more accurate they are, the better every planning skill will perform.

The documentation structure

Ultra Claude enforces a canonical documentation layout. Every document type has a specific home:

technology/architecture/ — system design, components, data flow, tech stack
technology/standards/ — coding conventions, patterns, anti-patterns
technology/testing/ — test strategy, commands, coverage standards
technology/rfcs/ — structured decision reviews for ambiguous choices
product/description/ — product vision, positioning
product/requirements/ — formal requirements, acceptance criteria
product/research/ — market research, competitor analysis
product/personas/ — evidence-based user personas
plans/ — feature and fix plans from planning modes
backlog/ — bugs, questions, ideas, tech debt (JSON files)

The /uc:docs-manager skill enforces this structure — it routes documents to the correct directory and catches violations. It also keeps each fact in a single canonical home: drift-prone content (schemas, values, procedures) lives in one place and other docs link to it with standardized anchored cross-links rather than restating it, while decision history stays in RFCs and design docs read as settled state. See Technology Standards for how this integrates with the enforcement loop.

After initialization

Once your project is initialized:

Review the generated docs — architecture, standards, and testing config. These inform every planning decision.
Plan your first feature — /uc:feature-mode
Or research first — /uc:discovery-mode if you're still defining what to build

Updating Ultra Claude

/uc:update

Updates Ultra Claude via the Claude Code plugin marketplace, restarts the tmux layout daemon (when tmux mode is active), and checks for pending project migrations. If structural changes occurred, it recommends running /uc:migrate in each project.