本地AI工作流

System requirements

Option 1: curl-bash install (recommended)

curl -fsSL https://qonqrete.sh/install.sh | bash

This downloads the latest release, then walks you through an interactive setup: 1. Choose your AI provider (OpenAI, DeepSeek, Gemini, Anthropic, Venice, CodeSeeq, and more) 2. Select a model from that provider's supported list 3. Enter your API key (auto-detected if already set in your environment)

After setup, QonQrete automatically configures all agents, runs init, and creates a starter tasq.md. You're ready to build.

For a specific version:

curl -fsSL https://qonqrete.sh/install.sh | bash -s -- v1.4.7

Version-specific install

curl -fsSL https://qonqrete.sh/install.sh | bash -s -- v1.4.7

For CI/non-interactive use:

QONQRETE_AUTO=1 QONQRETE_PROVIDER=deepseek QONQRETE_MODEL=deepseek-v4-flash \
  curl -fsSL https://qonqrete.sh/install.sh | bash

Local Node helper setup

The shipped container installs the default Node-based helper stack for JS/TS and HTML/CSS. For repo-local runs outside that container, install the pinned helper dependencies from .qonqrete/package.json:

cd .qonqrete
npm ci
npm run qonq-native-capabilities

npm ci is the supported reproducible workflow here; package-lock.json is the install authority for exact versions.

Runtime discovery prefers repo-local node_modules first, then global Node modules. Reduced local environments may still run, but Qontextor/Qompressor will honestly report and artifact any fallback path they had to use.

Quick Start (IDE)

Quick Start (CLI)

Quickstart

Option 2: Git clone + bootstrap

git clone https://github.com/illdynamics/qonqrete.git
cd qonqrete
./qonqrete-bootstrap.sh /path/to/your-project

Same interactive setup as the curl-bash install.

Option 3: IDE Extensions

Install QonQrete from the VS Code or JetBrains marketplace. On first launch, a setup wizard guides you through provider selection, model choice, and API key entry — then auto-configures everything. One click and you're ready.

Environment variable precedence

1. Real shell environment (OPENAI_API_KEY=... in your terminal) — always wins
2. IDE secure storage — injected only if the env var is not already set
3. Neither — the IDE prompts you to enter the key

AI Configuration Panel

Both IDEs include a "Set AI Configuration" command that lets you: - Set the provider and model for each primary AI agent (Qrystallizer, InstruQtor, ConstruQtor, InspeQtor) - Set API keys for each provider (stored securely) - See at a glance which keys are set and which are missing

Changes are written directly to .qonqrete/worqspace/config.yaml.

After deploying QonQrete to a workspace, the IDE will prompt you to configure AI providers and API keys.

CLI Reference

./qonqrete.sh init                           # Build container image
./qonqrete.sh tasq.md              # Task-first run
./qonqrete.sh run -f tasq.md       # Explicit task-file run
./qonqrete.sh run --auto                     # Autonomous mode
./qonqrete.sh run -b 6 -c 3                  # Sensitivity 6, 3 total iterations (build + repair passes)
./qonqrete.sh run --mode security            # Security-focused mode
./qonqrete.sh run --seed-repo                # Continue from current repo code (default run starts empty)
./qonqrete.sh run --no-sync                  # Skip repo-root sync-back only; qage/qodeyard artifacts remain
./qonqrete.sh run -a -n myproject            # Auto + save as qonstruction
./qonqrete.sh resume                         # Resume from previous qage
./qonqrete.sh status                         # Latest run state + manifest paths
./qonqrete.sh audit                          # Latest audit timeline + artifact paths
./qonqrete.sh clean                          # Interactive qage cleanup
./qonqrete.sh clean -A                       # Delete all qages
python worqer/qontextor.py --capabilities    # Current extractor capability report
python worqer/qompressor.py --capabilities   # Current compressor capability report
python -m worqer.smoqetester qodeyard --cycle 1 --config worqspace/config.yaml --json

Secure API Key Handling

API keys are never stored in plain-text settings files, terminal commands, or logs.

CLI reference

Usage: ./qonqrete.sh [COMMAND] [OPTIONS]
       ./qonqrete.sh <task-file.md> [OPTIONS]

Commands:
  init
  run
  resume
  status
  audit
  clean
  clean-outputs

Run options:
  -f, --task-file <path>
  -a, --auto
  -u, --user
  -m, --mode <name>
  -b, --briq-sensitivity <N>
  -B, --auto-briq-sensitivity
  -c, --cyqles <N>
  -n, --qonstruction-name <name>
  --seed-repo
  -s, --sqrapyard     (legacy alias for --seed-repo)
  -N, --no-sync       (skip repo-root sync-back; keep qage/qonstruction output)
  -d, --docker
  -p, --podman
  -q, --qage <name>   (resume/status/audit/clean target)
  -A, --all           (clean all qages)

Main workflow

1. Clarify — qrystallizer is the canonical intake stage
2. Clarification Gate — if readiness is NOT_READY, Qrane pauses in BLOCKED / RUN_WAITING_FOR_INPUT and captures bounded clarification responses
3. Qonstrictor — qonstrictor evaluates readiness and effective constraints before planning as a fallback guard
4. Plan — instruqtor emits execution blueprint, build groups, validation plan, and contract files
5. Estimate — calqulator emits estimation artifacts
6. Build — construqtor performs scoped staged writes with attempt/recovery evidence
7. Validate + Realize — deterministic validation and realization bundles are produced before judgment
8. Inspect — inspeqtor emits structured verdicts and repair plans
9. Continue only if justified — bounded repair or explicit linked continuation when the repair plan warrants it

Questioning policy: - only intake clarification asks user questions - once readiness is accepted, mid-run questioning is disabled

IDE integrations

IntelliJ / JetBrains plugin

Location: intellij-plugin/

Main capabilities in this repo snapshot: - tool window with run controls - settings/config UI - run, resume, clean, and qage browsing actions - status widget / shell verification concepts

Manual build/package:

cd intellij-plugin
./gradlew buildPlugin

VS Code

1. Install QonQrete from the VS Code Marketplace
2. Ctrl+Shift+P → QonQrete: Deploy to Workspace
3. Ctrl+Shift+P → QonQrete: Create Task File — creates the starter tasq.md
4. Ctrl+Shift+P → QonQrete: Run Tasq — runs the default task file directly, auto-init on first run

VS Code

Keys are stored in the OS keychain via VS Code's SecretStorage API. They are injected into the QonQrete process via the terminal's environment map — never in command text.

VS Code extension

Location: vscode-extension/

Main capabilities in this repo snapshot: - run canonical worqspace/tasq.md - run any Markdown file as a temporary tasq - sidebar control panel - status bar state reporting - init / run / resume / clean commands - qage browsing

Manual build/package:

cd vscode-extension
npm install
npm run compile
npx vsce package

provider: codeseeq also requires DEEPSEEK_API_KEY and the CodeSeeq CLI

export QWEN_API_KEY='...' export OPENROUTER_API_KEY='...' export VENICE_API_KEY='...' # required for provider: venice export MLX_API_KEY='...' # optional, used when provider: mlx export LLAMA_CPP_API_KEY='...' # optional, used when provider: llama-cpp ```

1. Initialize the Qage image

chmod +x qonqrete.sh
./qonqrete.sh init

Optional engine forcing:

./qonqrete.sh init --docker
./qonqrete.sh init --podman