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 — installs tmux if missing, configures it for Claude Code (fixes screen tearing via synchronized output passthrough)
Node.js — required for the tmux layout daemon that manages agent panes
Statusline — per-account usage tracking displayed in tmux
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 not found — setup installs it via your package manager (apt, brew, etc.)
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 — setup configures tmux's synchronized output passthrough to fix flickering in Claude Code

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. 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, and checks for pending project migrations. If structural changes occurred, it recommends running /uc:migrate in each project.