Qualia Framework v3 for Claude Code

3.0.0 · active · verified Tue Apr 21

Qualia Framework v3 is a harness engineering framework designed to structure and enhance AI-assisted development workflows within Claude Code. It provides an opinionated layer for planning, execution, verification, and deployment, moving beyond simple code generation to a structured project lifecycle. Currently at version 3.0.0, the framework integrates concepts from Anthropic's "Harness Design for Long-Running Apps," focusing on goal-backward verification, distinct agent separation (planner, builder, verifier), and robust Node.js-based hooks. It is not an application framework like Next.js; rather, it directs Claude's actions via a set of 19 slash commands ("skills") and manages project state, telemetry, and team interactions. Its release cadence follows major architectural improvements, with v3 incorporating significant lessons from prior iterations. Key differentiators include its verification contracts, agent-specific contexts to prevent "God prompt" issues, and cross-platform compatibility for its Node.js hooks. It runs on Node.js 18+.

Common errors

```
Error: Minimum Node.js version not met. Expected >=18, got vX.Y.Z
```
cause Running the CLI tool with an unsupported Node.js version.

fix Upgrade your Node.js environment to version 18 or newer (e.g., using `nvm install 18 && nvm use 18`).
```
Command failed: /bin/bash -c 'claude-code verify --version' (or similar error related to 'claude-code')
```
cause The Qualia Framework cannot detect or communicate with the Claude Code application.

fix Ensure Claude Code is correctly installed and configured on your system's PATH. Restart your terminal or IDE.
```
Invalid team code. Please check your input and try again.
```
cause An incorrect or expired team code was entered during the `npx qualia-framework-v2 install` process.

fix Re-run the installation command and enter the exact team code provided by your administrator. Verify its validity.
```
bash: /qualia-new: command not found (or similar for other /qualia- commands)
```
cause Attempting to run a Qualia Framework slash command directly in your operating system's terminal.

fix These commands are internal to Claude Code. Open Claude Code in your project and type the `/qualia-command` directly into its chat interface.

Warnings

gotcha Qualia Framework v3 is a workflow layer for Claude Code, not an application framework like Next.js or Rails. It does not generate code, run servers, or process data directly, but rather orchestrates Claude's development process.
Fix: Understand its role as an orchestration tool within Claude Code for structured AI-assisted development.
breaking The framework requires Node.js version 18 or higher. Installations on older Node.js versions will fail or result in unexpected behavior.
Fix: Ensure Node.js v18 or newer is installed. Use `node -v` to check your version and upgrade if necessary.
gotcha This framework is a companion to the Claude Code application and requires it to be installed and accessible. Without Claude Code, the framework's core slash commands are non-functional.
Fix: Install and configure Claude Code according to Anthropic's documentation before using the Qualia Framework.
gotcha The framework installs its core components into the `~/.claude/` directory rather than a standard `node_modules` location. This is by design for integration with Claude Code.
Fix: Be aware of the installation path; do not manually delete or move files within `~/.claude/` unless using `npx qualia-framework-v2 uninstall`.
gotcha Initial installation via `npx qualia-framework-v2 install` requires a 'team code' for authentication and configuration. This code is usually provided by your organization (e.g., from 'Fawzi' as per the README).
Fix: Obtain the correct team code from your administrator or team lead before attempting installation.
gotcha The primary interaction with the framework's 'skills' (e.g., `/qualia-new`, `/qualia-plan`) occurs as slash commands directly within the Claude Code chat interface, not as terminal commands in your shell.
Fix: After installation, open Claude Code in your project directory and type the slash commands directly into its input field.

Install

npm install qualia-framework-v2 npm
yarn add qualia-framework-v2 yarn
pnpm add qualia-framework-v2 pnpm

Quickstart

Installs the Qualia Framework CLI tool and explains how to interact with it via slash commands within Claude Code.

npx qualia-framework-v2 install
# Follow prompts for team code.

# After installation, open Claude Code in any project directory 
# and use the framework's slash commands directly in Claude's chat interface:
#
# /qualia-new       # Set up a new project
# /qualia-plan      # Plan the current phase
# /qualia-build     # Build it (parallel tasks)
# /qualia-verify    # Verify it actually works

view raw JSON →