QonQrete VS Code Extension

Run QonQrete directly from VS Code

This extension integrates the QonQrete Agentic AI System into VS Code.

AI Configuration (v1.4.7)

• The shared AI configuration surface now targets the four primary runtime agents:
  • qrystallizer, instruqtor, construqtor, inspeqtor
• Default binding is venice / deepseek-v3.2.
• Local-only runtime providers (mlx, llama-cpp) are not shown in the shared provider/model picker.

Platform Support

Important: On Windows without bash, the extension blocks execution entirely rather than attempting a broken fallback.

Shell Detection

The extension searches for bash in this order:

Unix (Linux/macOS):

1. $SHELL environment variable (if contains "bash")
2. /bin/bash

Windows:

1. GIT_BASH environment variable (custom path support)
2. C:\Program Files\Git\bin\bash.exe
3. C:\Program Files (x86)\Git\bin\bash.exe
4. C:\Windows\System32\bash.exe (WSL)
5. C:\msys64\usr\bin\bash.exe

Custom Installations: Set the GIT_BASH environment variable to your bash path, or use the qonqrete.qonqretePath setting.

Shell Verification

On activation, the extension:

1. Detects available bash shell
2. Verifies shell works via bash --version
3. Status bar shows state:
   • (verifying...) — detection done, verification in progress
   • Ready — verified and ready
   • (shell error) — verification failed

Clean Contract: canExecute() returns false until shell is verified. All run paths (command palette AND sidebar) wait for verification to complete before proceeding.

Retry on Failure: If verification fails due to a transient issue, the extension clears the cached result and allows re-verification on the next run attempt.

Run State Detection

The extension uses a marker file with polling fallback:

1. Creates unique marker file (.qonqrete_run_*.marker)
2. Appends to command: echo $? > marker
3. Detection via:
   • fs.watch() (primary)
   • 1-second polling (fallback for unreliable filesystems)
4. Reads exit code from marker file
5. Updates status accordingly

Run States

Honest Limitation: If marker file is not detected, the extension reports timeout — it does NOT claim success or failure when it doesn't know.

Orphan Cleanup

On activation, the extension automatically:

• Restores any orphaned tasq.md backup from interrupted sessions
• Cleans up stale marker files

This handles the edge case where a previous session was hard-killed mid-run.

Features

Command Palette

• QonQrete: Run Tasq — Run the default project task file
• QonQrete: Resume Run — Resume from a Qage
• QonQrete: Init Workspace — Build container image
• QonQrete: Clean Qages — Remove Qage directories
• QonQrete: Show Status — Display status including shell verification

Context Menu

• tasq.md files: Runs that specific tasq.md
• Other .md files: Runs the selected markdown file directly as task input

Sidebar

• Configuration: Sensitivity, cycles, mode, autonomous, repo-seed toggle
• Run output control: Optional --no-sync toggle to keep outputs in qage/qonstruction paths
• Advanced: Qonstruction name, container engine
• Status: Version, image, default task file, shell (with verification indicator)
• Qage Browser: Expandable list with artifact counts and file links

Status Bar States

Qonstruction Name Sanitization

When you enter a qonstruction name with invalid characters:

1. Extension shows warning: Name sanitized: "my name!" → "my_name_"
2. You choose "Use Sanitized Name" or "Cancel"
3. Only proceeds if you explicitly accept

Allowed characters: a-z, A-Z, 0-9, _, -

Installation

cd vscode-extension
npm install
npm run compile
npx vsce package
code --install-extension qonqrete-vscode-1.4.7.vsix

Settings

CLI Flag Mapping

The extension correctly maps to real qonqrete.sh flags:

Resume: ./qonqrete.sh resume --qage QAGE_NAME [--auto] Clean: ./qonqrete.sh clean --qage QAGE_NAME or --all

Limitations

What the extension CAN do:

• Detect exit codes via marker file
• Block execution until shell is verified
• Show honest timeout state when outcome unknown
• Auto-recover orphaned backups on activation
• Support custom bash paths via GIT_BASH env var

What the extension CANNOT do:

• Parse terminal output in real-time
• Cancel a running process gracefully
• Work on Windows without bash
• Guarantee exit code if terminal is killed before marker written

Known Edge Cases:

• Hard terminal kills can lose marker file → timeout state
• Custom bash installs need GIT_BASH env var or settings

Validation Reality

Deterministic validation in the current bridge is strongest for Python. Other ecosystems still run through the workflow, but deterministic compile/test coverage is weaker.

Requirements

• VS Code 1.80.0+
• Docker or Podman
• QonQrete repository with qonqrete.sh
• Windows: Git Bash, WSL, or MSYS2 (required)

Development

npm install          # Install dependencies
npm run compile      # Build TypeScript
npm run watch        # Watch mode
npm run package      # Create .vsix

Press F5 in VS Code to launch extension host.

License

QonQrete is licensed under the Apache License, Version 2.0. See the LICENSE file for full text.

Copyright (c) 2026 | QonQrete | Built by Ill Dynamics (Ricky van Poppel)