Codex · Claude Code · Gemini CLI · terminal-capable agents

Use QZX to understand a project before your AI agent changes it

Go from installation to a useful project briefing for Codex, Claude Code, Gemini CLI, or another terminal-capable agent: inspect the directory tree, discover technologies and validation settings, and profile source languages. Keep the results as structured evidence instead of asking the agent to guess.

Start the quickstart See recorded output

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 --pre --upgrade qzx
qzx version --json
qzx getCurrentDateTime --output-format iso --json

Use the generated installation command above when you control the selected Python environment. For a standalone isolated CLI, pipx install --pip-args='--pre' 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 . --json

Prefer a readable summary?

Run the diagnosis without --json for a prioritized briefing: technologies, dependencies, Git state, observed findings and a next step for each. Test and build commands remain suggestions, explicitly marked as not run. Add --json whenever an agent needs the complete evidence.

qzx diagnoseProject .

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.

Step 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.

OpenAI: persistent context with AGENTS.md Anthropic: Claude Code memory Gemini CLI: GEMINI.md context

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.