AI agent quickstart

Give an AI agent a predictable QZX workflow in five minutes

Install the published package, discover what is really available, start with read-only commands, and request JSON that Codex, Claude Code, Gemini CLI, or another terminal-capable agent can inspect without guessing at columns.

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 ask the local installation for its actual catalog.

python -m pip install --upgrade qzx
qzx version --json
qzx qzxListCommands --json

The website can document development capabilities that are newer than the wheel. 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.

Step 2 · Read before writing

Run a small read-only confidence check

qzx about --json
qzx getCurrentDate --json
qzx currentDir --json
qzx qzxHelp findFiles --json

What the agent should verify

  • The process exits successfully and stdout is one valid JSON document.
  • success is a boolean and message explains the result.
  • The requested command appears in qzxListCommands.
  • The command page marks the operation as read-only, mutating, privileged, or networked.
  • Machine-specific values remain truthful; only the interface is normalized.

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` and `qzx qzxListCommands --json`.
- 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.