QonQrete VS Code Extension

Run QonQrete directly from VS Code

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

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 worqspace/tasq.md
• 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: Copies file as temporary tasq.md (original restored after run)

Sidebar

• Configuration: Sensitivity, cycles, mode, autonomous, sqrapyard
• Advanced: Qonstruction name, container engine, TUI, wonqrete
• Status: Version, image, tasq.md, 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.1.9.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
• Temp tasq restoration depends on shell command chaining
• Custom bash installs need GIT_BASH env var or settings

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 GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for full text.

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