Codex · Claude Code · Gemini CLI · terminal-capable agents
Use QZX to understand a project before your AI agent changes it
Install QZX, prove the CLI works with one read-only check, then turn an unfamiliar repository into structured evidence for Codex, Claude Code, Gemini CLI, or another terminal-capable agent.
python -m pip install --upgrade qzx
qzx getCurrentDateTime --output-format iso --jsonNo account or project modification is required for the first check. Continue below when you are ready to inspect a real codebase.
Step 1 · Install and identify
Verify the package before delegating work
Use a standard CPython build that satisfies the package metadata. These commands install the current published release, identify it, and complete the same canonical first success shown by the CLI.
python -m pip install --upgrade qzx
qzx version --json
qzx getCurrentDateTime --output-format iso --jsonUse the generated installation command above when you control the selected Python environment. For a standalone isolated CLI, pipx install qzx is also supported. If pip reports externally-managed-environment, prefer pipx rather than overriding the system Python. Choose the right installation path. If a command is missing, update QZX and check qzx version --json before continuing.
Why this command: Confirm QZX with a fast, read-only ISO timestamp. The website can document development capabilities that are newer than the wheel, so treat the installed catalog—not an article or prompt—as the source of truth for what this machine can execute. Review Python and platform compatibility. Machine-readable results follow the open QZX Result Contract v1.
Step 2 · Your first useful workflow
Turn an unfamiliar repository into a project briefing
After completing Step 1, open a terminal inside the project you want to inspect. The dot means that project directory, not your whole disk. Run these three commands separately; they inspect the project without running its tests, build scripts or installers.
qzx getProjectTree . 2 --max_entries 200 --json
qzx diagnoseProject . --json
qzx projectLanguages . --jsonNeed help or want to share how it went?
1. Understand the structure
Read tree_text for a quick overview or tree_structure in code. The example retains at most 200 entries through two descendant levels. Check details.entry_limit_reached and details.scan_complete before treating the view as complete.
2. Find the next useful action
Inspect details.technologies, dependency manifests and details.summary.issues. The diagnostic discovers validation configuration; it does not execute that configuration or certify that tests passed.
3. Know what you are working with
Read summary.primary_language and languages. Documentation and configuration remain separate in supporting_formats, rather than being presented as application code.
What to ask your agent next
Using these QZX results, summarize the project, identify the most important observed issue, and propose one next step. Separate observed facts from assumptions. Do not claim that tests passed and do not modify files or run project scripts yet.
Check available commands and parameters locally:
qzx listCommands file
qzx help findFiles
qzx help diagnoseProject --json- Explore the installed catalog
- Filter the installed catalog to commands related to files.
- Understand before running
- Inspect parameters, examples, maturity, and safety before execution.
Did this workflow help you?
After trying it in your terminal, tell Alejandro what happened—or go straight to help. No account or explanation is needed for the optional response.
Optional: your selected category is sent with the existing website analytics session. We do not read your terminal, project, destination or clipboard. This is your assessment, not an automatic check. How this response is used
Keep the workflow for your next project. QZX is free; optional support helps Alejandro maintain its commands, guides and tests.
Support QZX developmentChoose pip for a Python environment you control, or pipx for an isolated CLI. The guide explains managed environments and checking your first result.
Choose an installation pathRun qzx version --json and check the exact command in the installed help. Keep a reproducible error and the relevant versions before requesting help; do not share secrets.
Find the command referenceA completed diagnostic is not the same as a healthy target. Read the command-specific fields and limitations; the guide separates observed facts from assumptions.
Review the result fieldsFound a reproducible problem? Open the existing bug report form, review its fields and decide what to share. Reports are public and require GitHub sign-in.
Report a workflow problem to AlejandroStep 3 · Add durable instructions
A project instruction block agents can follow
Place a reviewed version of this block in the project instruction mechanism your agent supports. Codex can use AGENTS.md, Claude Code uses CLAUDE.md, and Gemini CLI uses GEMINI.md. The terminal tool must still be enabled according to that product's own permission model.
## QZX command policy
- Use QZX only when a documented command matches the task.
- Before first use, run `qzx version --json`, `qzx getCurrentDateTime --output-format iso --json`, `qzx listCommands file`, and `qzx help findFiles`.
- Add `--json` when another program or agent consumes the result.
- Check both the process exit code and the `success` field.
- Read `message` and the command-specific fields; do not infer success from missing errors.
- Start with read-only commands.
- Before a mutation, inspect the command page, preview/dry-run support, required approval, and backup behavior.
- If QZX does not model the operation, use a maintained native API or the shell instead.
- QZX is not a sandbox and runs with the current user's permissions.Step 4 · Choose the right interface
QZX is one useful layer, not every layer
Use QZX CLI
For a documented local system, file, development, or network operation where one cross-platform command and structured output help.
Use MCP
When an MCP-compatible host needs discoverable tools, resources, or prompts from a local or remote server with protocol-level lifecycle and authorization concerns.
Use a direct API
When application code needs a maintained typed SDK, in-process control, service-specific authentication, or the strongest domain contract.
These choices can be combined: an MCP server can call a CLI, and a CLI can call an operating-system API. The right question is which boundary gives the host the clearest contract and the least unnecessary complexity. Read the practical MCP vs CLI vs API guide.
Ready to delegate
Pick one read-only command and inspect the real result
The catalog documents availability, parameters, safety properties, the result contract, and whether the displayed output is recorded or representative.