NAQUADA
Open Naquada
Verifiable workflow

Naquada inside your IDE

Install the Naquada extension for VS Code

Connect Codex to the Naquada Orchestrator, approve a plan, and receive images, videos, audio, and 3D files at the requested path in your project.

Before you start

The extension drives the local Rust CLI. Both components are required.

  • VS Code 1.96 or newer.
  • A Naquada account on the production service.
  • The Naquada CLI available as the naquada command.
  • Codex in VS Code to launch pipelines from chat.

Check

Visible result: naquada --version returns in the integrated terminal.

Install both components

1

Install the CLI

Follow the macOS, Windows, or Linux guide first. The CLI stores your session in the operating-system credential vault.

Naquada CLI guide →
2

Install the extension

Install “Naquada for Codex” from the Marketplace, then reload VS Code.

Distribution link not configured

This page is ready, but the operator must set NEXT_PUBLIC_NAQUADA_VSCODE_MARKETPLACE_URL to the official listing before publication. Do not install a package from another publisher.
VS Code CLI
code --install-extension naquada.naquada-vscode
3

Verify the installation

A Naquada icon appears in the activity bar and “Naquada: sign in” is available in the Command Palette.

Connect the project and Codex

1

Sign in

Open the Command Palette (⇧⌘P on macOS, Ctrl+Shift+P on Windows/Linux), run “Naquada: sign in,” then approve the code in your browser.

Terminal
naquada login
2

Link the current folder

Run “Naquada: link this project.” Choose a stable name and tag. Naquada only creates the local .naquada folder and a remote context owned by your account.

Terminal
naquada project link --name "My project" --tag my-project
3

Register Naquada with Codex

Run “Naquada: connect Codex via MCP,” confirm, then reload the window. The CLI command below performs the same registration.

Terminal
naquada setup codex --apply

Concrete check

Open the MCP server list in Codex: naquada is enabled and its planning tools are visible.

Create a first asset without leaving VS Code

Request a precise result and always provide a relative destination. Codex prepares the plan; paid execution only starts after the approval required by your settings.

Codex prompt
Use Naquada to create a 512 × 512 pixel-art magic chest icon with a transparent background. Save the original to assets/generated/chest.png. Show me the plan and estimated cost before execution.

Review the model, configuration, inputs, estimated cost, and especially assets/generated/chest.png, then approve.

Expected result you can verify

  • The run appears in “Naquada — Runs and assets.”
  • The local receipt names the Naquada tool, approved plan, and final path.
  • assets/generated/chest.png exists and opens in VS Code.
  • The delivered file hash is recorded in .naquada/runs/<run-id>.json.

Understand where files go

Every path supplied to Naquada is relative to the open project root.

  • .naquada/runs/ stores receipts required for tracking and recovery.
  • .naquada/assets/ is temporary delivery staging, not a synchronized library.
  • The verified file is moved to the final path requested by the AI.
  • Local references are uploaded only when a specific file or allowed folder is explicitly selected.

Name collisions

Naquada overwrites only when the AI explicitly requires it. Otherwise, image.png becomes image-02.png, for example.

What Naquada never does implicitly

VS Code workspace trust and explicit consent remain required for sensitive actions.

  • No full-repository scan or upload.
  • No automatic synchronization of your online asset library.
  • No Git commands, commits, or branch changes.
  • No asset download without an approved run and local receipt.
  • The interactive session is stored in Keychain, Windows Credential Manager, or Linux Secret Service.

Close VS Code without losing a generation

Generation continues on Naquada. The extension does not block the chat while it waits.

  • After restart, it reads only approved receipts in .naquada/runs/.
  • It resumes incomplete downloads and verifies SHA-256.
  • A notification confirms delivery or reports that recovery is needed.
  • You can run “Resume delivery” manually from the Naquada view.

Diagnose the setup in under a minute

Run “Naquada: diagnose integration” or the following command.

Terminal
naquada --json doctor
  • authenticated must be true.
  • projectLinked must be true.
  • apiReachable must be true.
  • gitTouched must always be false.

Result

When ok is true, the account, project, production API, and recovery directories are ready.