zai

An extensible AI coding assistant for the terminal.

zai can chat about a project, inspect and modify files, run commands, resume project-specific sessions, switch between model providers, and integrate with plugins and MCP servers.

What is zai?

zai is the terminal CLI. It is not tied to one AI model. It connects to the provider you configure, then uses that provider's selected model ID.

Cloud providers need their own API key. Ollama runs on your local machine and does not need a cloud API key.

Which model does zai use?

Run:

zai model list
zai auth status
zai context

The model list shows the alias, provider, display name, actual model ID, local or cloud status, and whether a key is configured.

Provider	Cloud/local	Key needed	Setup
Groq	Cloud	Yes	zai auth login groq
Gemini	Cloud	Yes	zai auth login gemini
OpenAI	Cloud	Yes	zai auth login openai
Anthropic/Claude	Cloud	Yes	zai auth login anthropic
OpenRouter	Cloud	Yes	zai auth login openrouter
Cerebras	Cloud	Yes	zai auth login cerebras
Qwen/DashScope	Cloud	Yes	zai auth login qwen
Ollama	Local	No cloud key	Start Ollama, then zai model test ollama

Quick tester flow:

pip install --upgrade --no-cache-dir zai-cli
zai --version
zai
/help
/model
/auth status
/context

Requirements

• Python 3.10 or newer
• At least one supported API key, or a running local Ollama server
• Optional: Playwright for browser commands
• Optional: Node.js and npx for MCP servers

Install

pip install zai-cli

The PyPI distribution is named zai-cli; the installed command and Python package remain zai.

Start in 60 seconds

python -m pip install --upgrade --no-cache-dir zai-cli
zai

If no provider key is configured, zai will offer setup immediately. Follow the prompt, choose a provider, paste your own API key, then start working in the same terminal.

First run

Run zai inside the folder you want to work on:

cd path/to/project
zai

Useful first commands inside interactive mode:

/              Show commands
/setup         Configure or update provider keys
/model         Show available models
/review        Review current changes
/exit          Leave zai

You can also type normally, for example:

explain this project
find bugs in the auth code
create a README for this folder

Recommended free providers

Users must use their own API keys. Do not share your personal key.

• Gemini: free starting point for general use, https://aistudio.google.com/app/apikey
• Groq: free and fast, https://console.groq.com/keys
• OpenAI: paid, https://platform.openai.com/api-keys

Keys are saved locally in ~/.zai/.env. You can inspect current status with:

zai doctor
zai model list

Authentication

zai uses provider API keys for its own model calls. Account login for external tools such as Codex or Claude Code is separate.

Check what is connected:

zai auth status
zai auth doctor

Connect a provider API key:

zai auth login gemini
zai auth login groq
zai auth login openai
zai auth login anthropic

When prompted, authentication login can send one tiny live request to validate the key. The result identifies the resolved model and gives a recovery command for invalid credentials, quota limits, model errors, or network failures.

Remove a saved API key from zai:

zai auth logout groq

Credential boundaries:

• zai stores provider API keys in ~/.zai/.env by default.
• zai never prints raw keys.
• Do not paste API keys into normal chat prompts, issues, tickets, or logs.
• zai does not copy Codex or Claude private token files.
• If codex or claude is installed, zai auth login openai or zai auth login anthropic can offer to run the official external CLI login, after asking for confirmation.
• OpenAI/Anthropic API keys power zai; ChatGPT/Codex or Claude account login powers those official external CLIs.

Troubleshooting

If zai still shows an older version:

python -m pip install --upgrade --force-reinstall --no-cache-dir zai-cli
zai --version

If the zai command is not found:

python -m zai --version
python -m pip show zai-cli

If no provider is available:

zai doctor
zai auth status
zai setup

If a key is invalid or missing:

zai auth login groq
zai model test groq

If an unexpected command or interactive error occurs, zai prints a short diagnostic ID and stores a bounded, secret-redacted record locally. Inspect it with:

zai diagnostics
zai diagnostics show <id>
zai diagnostics path

Inside interactive mode, /diagnostics shows the five most recent records. Diagnostics are stored in ~/.zai/logs/diagnostics.jsonl; use zai diagnostics clear to remove them.

If external Codex or Claude login fails, use their official CLI directly:

codex login
codex login --device-auth
claude login

If codex or claude is not found, install the official CLI first or use a provider API key with zai auth login <provider>.

For local development:

pip install -e ".[all,dev]"
python -m pytest -q

Optional live service checks:

ZAI_RUN_LIVE_TESTS=1 python -m pytest tests/integration -m integration

Optional selectors include ZAI_LIVE_PROVIDER=groq, ZAI_LIVE_BROWSER=1, and ZAI_LIVE_MCP=1. Live tests can consume provider quota or download/start external tools.

Quick start

# Configure providers
zai setup

# See which slash commands are available before entering interactive mode
zai commands

# Start the interactive coding assistant in the current directory
zai

# One-off chat
zai ask "Explain recursion"

# Explicit chat command
zai chat "Explain this project"

# Work with code
zai skill review main.py
zai repo map
zai run script.py
zai git status

During zai setup, add at least one API key. Gemini and Groq are good free starting points; OpenAI is paid. Keys are saved locally in ~/.zai/.env.

• Gemini key: https://aistudio.google.com/app/apikey
• Groq key: https://console.groq.com/keys
• OpenAI key: https://platform.openai.com/api-keys

Inside interactive mode, type / and press Tab to see slash commands, or run /help and /commands.

Project memory

zai can keep small project-specific memory in the folder you run it from:

.zai/project_memory.json

This is separate from conversation session history. It stores a compact summary of project signals such as languages, frameworks, important files, common setup, test, and run commands, plus facts you explicitly ask zai to remember. It does not store API keys, .env contents, tokens, passwords, or full source files.

Create or refresh memory:

zai memory refresh
zai memory project

Inside interactive mode:

/memory project       Show project memory
/memory refresh       Refresh detected project summary
/remember <fact>      Save a project fact
/forget <fact-or-id>  Delete a saved fact

When zai starts in a folder that already has .zai/project_memory.json, it loads a short pinned summary so future answers can use that folder's context. Different folders keep different memories.

Project rules

Add project instruction files when you want zai to consistently follow repo rules without copy-pasting them into every prompt.

Supported files:

ZAI.md
.zai/rules.md
AGENTS.md
CLAUDE.md
GEMINI.md

When zai starts, it loads bounded text from these files in the project root and current folder, redacts obvious secrets, and pins the rules into model context. Use these files for coding style, preferred test commands, folders to avoid, release steps, and project-specific constraints.

Inspect loaded rules:

zai rules
/rules
zai context
/context

Project rules are different from project memory:

• Project rules are explicit instructions written by the user/repo.
• Project memory is a generated or remembered summary in .zai/project_memory.json.
• Repo maps are generated structure summaries used on demand.
• Session history is the current or saved conversation.

Memory types:

• Session history: previous conversation messages saved globally under ~/.zai.
• Project memory: small per-folder facts in .zai/project_memory.json.
• Project rules: explicit instruction files such as ZAI.md or .zai/rules.md.
• Repo map: generated structure summary used for repository questions; it is not long-term memory.

Main commands

zai                         Start the interactive project assistant
zai doctor                  Check install, keys, and provider readiness
zai commands                List interactive slash commands
zai ask <message>           Send a one-off message
zai chat [message]          Chat with the configured model
zai --plain ask <message>   Emit only plain final response text
zai --debug ...             Show full tracebacks for unexpected errors

zai file read <path>        Read a file
zai file list [directory]   Recursively list files
zai run <file.py>           Run a Python file
zai repo map                Build a repository map
zai repo ask <question>     Ask about a repository
zai search <query>          Search general DuckDuckGo web results and summarize

zai skill <name> <file>     Run a built-in or plugin skill
zai git status              Show Git status
zai git log                 Show recent commits
zai git diff                Show changes
zai git commit              Generate and optionally use a commit message
zai git review              Review current changes

zai vision <image>          Analyze an image with Gemini or Groq
zai browser scrape <url>    Extract visible page text
zai browser screenshot <url>
zai browser analyze <url>

zai model list              List configured models
zai model set <name>        Set the default model
zai model fallback on|off   Enable or disable automatic provider fallback
zai model add <name>        Add a custom model alias
zai model remove <name>     Remove a custom model alias
zai model configure <name>  Set timeout and retry policy
zai model info <name>       Show effective model configuration
zai model test <name>       Verify credentials/model and show recovery guidance
zai auth status             Show API-key and external CLI auth status
zai auth login <provider>   Connect a provider API key
zai auth logout <provider>  Remove a provider API key from zai
zai auth doctor             Show auth troubleshooting guidance
zai context                 Show loaded project context status
zai rules                   Show loaded project instruction files
zai memory show             Show last task metadata
zai memory projects         List remembered projects
zai memory project          Show project-scoped memory
zai memory refresh          Create or refresh project-scoped memory
zai memory remember <fact>  Save a project fact
zai memory forget <id/text> Delete a project fact
zai memory clear            Clear memory metadata

zai hook list
zai hook add <event> <command>
zai hook remove --id <id>

zai mcp available
zai mcp list
zai mcp add <name>
zai mcp connect <name>
zai mcp tools
zai mcp remove <name>

zai plugin list
zai plugin new <name>
zai plugin install <name>
zai plugin trust <name>
zai plugin untrust <name>
zai plugin enable <name>
zai plugin disable <name>
zai plugin remove <name>

Run zai --help for the authoritative command list.

Plugin and browser security

Plugins execute Python with the same operating-system permissions as zai. Local and pip-installed plugins therefore remain blocked until their current code fingerprint is explicitly trusted:

zai plugin install example
# Review the package or ~/.zai/plugins/example.py first
zai plugin trust example

Every local plugin requires a <name>.plugin.json sidecar manifest. Packaged plugins require zai-plugin.json in their distribution. Manifests declare the plugin name, source, version, and requested permissions from: project_read, project_write, network, subprocess, and secrets.

Trust fingerprints bind both code and manifest. If either changes, the plugin is blocked until reviewed and re-trusted. Installing or enabling a plugin asks for explicit confirmation. Agent-triggered plugin tools also show declared permissions and ask for confirmation. Use zai plugin untrust <name> to revoke trust.

Browser commands accept only credential-free public HTTP(S) URLs. Localhost, private/link-local addresses, unsafe redirects, and non-HTTP schemes are blocked. Screenshot output is restricted to PNG/JPEG paths inside the current project. Browser downloads are disabled, top-level documents are capped at 2 MB when the server reports their size, and search responses are capped at 1 MB.

Vision input is decoded and verified before it is sent to a provider. Images are limited to supported raster formats, 10 MB, and 40 megapixels.

Interactive commands

Inside zai interactive mode:

/help                       Show interactive commands
/files                      List current project files
/diff                       Show the Git diff
/undo                       Undo the latest recorded filesystem action
/plan <task>                Generate a plan before execution
/test                       Run pytest and request fixes for failures
/watch                      Toggle file-change monitoring

/resume [name]              Resume the latest project session or a named one
/session save [name]        Save the current conversation
/session load <name>        Load a named conversation
/session list               List saved conversations
/session search <query>     Search current-project conversations
/session rename <old> <new> Rename a saved conversation
/session delete <name>      Delete a saved conversation

/model list                 List models
/model <name>               Change model for this interactive session
/providers                  Show provider connection status
/context                    Show loaded project context status
/rules                      Show loaded project instruction files
/memory                     Show last task metadata
/commands                   List built-in and plugin slash commands

Command names support safe typo correction when one close, unambiguous match exists.

Interactive input also provides:

• persistent history in ~/.zai/input_history with Up/Down navigation;
• Tab completion for slash commands, models, sessions, and project paths;
• multiline input with Alt+Enter or Ctrl+J;
• Ctrl+C to cancel the current input or operation without ending the session;
• a basic Rich prompt fallback in redirected or unsupported terminals.

You can reference files in natural prompts with @file:

explain @app.py
fix @src/main.py
compare @README.md and @CHANGELOG.md

zai loads bounded text from valid referenced files and appends it to the prompt context. Hidden files, sensitive-looking paths, binary files, and very large files are skipped with a note instead of crashing the session.

How much of my project does zai see?

zai starts from the folder where you run it. It does not load every file in a large repository into every prompt.

Use zai context or /context to inspect the current folder, whether project memory exists, whether a repo-map cache is available, and how many conversation messages are loaded in the current interactive session.

For token/context usage:

zai context tokens
zai context summary
/context tokens
/context summary
/compact

zai context tokens and /context tokens show an approximate provider-neutral token estimate, the configured context limit, remaining tokens, and whether the session is approaching the compaction threshold.

Project memory is separate from current model context. It is a small .zai/project_memory.json summary created with zai memory refresh or /memory refresh.

Repo maps are summaries/indexes used on demand for repository questions. They are not full source files loaded into every model call. If a file has not been read or indexed for the current task, treat it as not loaded yet.

For long interactive sessions, /compact summarizes older conversation and tool history so the active session can continue with less context pressure. The summary preserves the goal, decisions, recent work, commands/results where visible, and pending context in a compact form.

All chat, workflow, utility, and agent requests use a model-aware context pipeline:

• the active provider's configured context window sets the request budget;
• system prompts, tool schemas, and output space are reserved before messages;
• initial project instructions and explicitly pinned messages are retained;
• assistant tool calls remain paired with their tool-result messages;
• oversized tool results keep their beginning and end with an omission marker;
• requests are bounded to fit the selected model's context limit;
• context usage uses a conservative shared token estimate, while provider response usage is retained where the SDK reports it.

This keeps requests bounded. Compaction is still approximate, so save important stable project facts explicitly with /remember <fact> or zai memory remember <fact>.

Providers and fallback

The default fallback order is:

gemini -> groq -> cerebras -> openrouter -> qwen -> claude -> gpt4o -> ollama

Providers without an API key are skipped. Ollama is used only when its local service is available. Provider quotas and model availability are controlled by their respective services and can change independently of zai.

All provider transports return the same response shape and stable error categories. When fallback moves from a native-tool provider to a legacy provider, earlier tool calls/results are converted to bounded text history instead of sending invalid provider-specific roles.

When an attempted model fails, zai reports the model, a stable failure category, secret-redacted provider detail, and the recommended recovery action before trying the next configured model. If every model fails, the final error lists the complete attempt chain. In --plain mode these diagnostics go to stderr, leaving successful response text on stdout.

Supported configuration keys:

GEMINI_API_KEY
GROQ_API_KEY
CEREBRAS_API_KEY
OPENROUTER_API_KEY
QWEN_API_KEY
ANTHROPIC_API_KEY
OPENAI_API_KEY

Keys are stored in ~/.zai/.env by zai setup.

Sessions and undo

• Successful interactive turns are automatically saved per project.
• /resume loads the latest session for the current project.
• Sessions have stable IDs and can be resumed by name or ID prefix.
• Ambiguous partial names are rejected instead of loading the wrong session.
• Named and legacy sessions remain supported.
• The latest 100 named sessions are retained; project auto-sessions remain one per project.
• Undo records are stored under the project's .zai/undo/ directory.
• File creation, file edits, folder creation, and path renames are undoable.
• A non-empty generated folder is never removed by /undo.

Add .zai/ to the project's .gitignore to avoid committing local undo data.

Safety

Model-controlled filesystem actions are restricted to the current project. Writes, edits, folder creation, and renames are verified after execution. Failed file verification triggers a best-effort rollback.

Shell commands are classified as:

• safe: executed directly;
• approval required: deletion, dependency changes, downloads, Git state changes, shell chaining, and redirection;
• blocked: destructive operations such as git reset --hard, disk formatting, shutdown commands, and destructive database statements.

Commands run as direct argument arrays with shell=False. Shell chaining, redirection, command substitution, and shell interpreters are rejected. User-defined slash-command substitutions can run only safe allowlisted commands. Hooks also use direct executable invocation.

Tool calls use validated JSON schemas. Legacy XML tool calls remain accepted temporarily for compatibility.

Hooks

Available hook events:

PreToolUse
PostToolUse
SessionStart
SessionEnd
UserPromptSubmit

Hook commands receive event data as JSON on standard input. Exit code 2 blocks the action for blocking events.

Example:

zai hook add PreToolUse "python validate_tool.py"

Browser support

Browser commands require Playwright:

pip install playwright
playwright install chromium

Development status

zai is currently version 0.1.0 and should be treated as a strong beta. See CHANGELOG.md for release notes and known limitations.

Current quality baseline:

• 440 non-live tests passing
• 76% measured code coverage with a 75% CI minimum
• Python 3.10–3.14 test matrix
• installed-wheel smoke tests on Linux, Windows, and macOS
• wheel and source-package validation with Twine
• Ruff critical-rule linting, scoped MyPy checks for browser/search and persistence safety modules, and dependency auditing
• project-scoped filesystem safety
• direct command execution with shell=False
• persistent sessions and undo
• structured and validated tool calls

Review generated changes and command output before using them in important repositories.

Roadmap to a stable CLI

The following phases define the remaining work required before calling zai stable. Phases should be completed in order because later work depends on the reliability established by earlier phases.

Phase 1: Live service validation

Goal: prove that the mocked provider and integration tests match real external services.

Validated on Windows on June 23, 2026:

• Groq chat and native tool-call flows;
• DuckDuckGo general web search;
• Playwright Chromium scrape and screenshot flows;
• filesystem MCP connection, tool discovery, and list_directory execution.

Gemini and a paid provider remain pending because credentials were not available in the validation environment.

Implementation work:

1. Test Groq with a real API key.
2. Test Gemini with a real API key.
3. Test at least one paid provider when credentials are available.
4. Run the DuckDuckGo live search test.
5. Install Playwright and test browser scrape and screenshot commands.
6. Test one MCP server, preferably filesystem or GitHub.
7. Verify provider fallback by intentionally making the preferred provider unavailable.
8. Record provider-specific errors and normalize any response differences.

Relevant locations:

tests/integration/test_live_services.py
zai/providers/
zai/tools/search.py
zai/tools/browser.py
zai/mcp/

Commands:

# Use a configured provider
ZAI_RUN_LIVE_TESTS=1 ZAI_LIVE_PROVIDER=groq \
python -m pytest tests/integration -m integration -v

# Browser validation
ZAI_RUN_LIVE_TESTS=1 ZAI_LIVE_BROWSER=1 \
python -m pytest tests/integration -m integration -v

# MCP validation
ZAI_RUN_LIVE_TESTS=1 ZAI_LIVE_MCP=1 \
python -m pytest tests/integration -m integration -v

Definition of done:

• Groq and Gemini each complete chat and agent tool flows.
• Browser scrape and screenshot work on Windows and Linux.
• At least one MCP server connects, lists tools, and executes a tool.
• Provider fallback is demonstrated against real providers.
• Live failures produce actionable user-facing messages.

Phase 2: Terminal user experience

Goal: make interactive use comfortable for long coding sessions.

Completed:

• persistent history and Up/Down navigation using prompt_toolkit;
• slash-command, model, session, and project-path completion;
• multiline prompts using Alt+Enter or Ctrl+J;
• visible input/operation cancellation without ending the session;
• basic prompt fallback for terminals without an interactive screen buffer.

Global --debug enables full tracebacks for unexpected errors. Global --plain makes one-shot AI requests use non-streaming calls and emit the final response without model or token metadata, which is suitable for scripts and CI.

Ctrl+C uses a shared cooperative cancellation token across fallback attempts, agent turns, subprocess commands, MCP requests, and plugin-call boundaries. Running subprocesses are terminated, MCP servers receive cancellation notifications, and session/undo state is saved only for completed turns. Synchronous provider SDK calls are interrupted by Ctrl+C where the SDK permits; otherwise their result is discarded at the next cancellation boundary.

Definition of done:

• Interactive history survives restart.
• Common commands and paths autocomplete.
• Long multiline requests can be entered naturally.
• Cancellation does not corrupt session or undo state.

Phase 3: Model and provider configuration

Goal: remove hard-coded model assumptions and make provider configuration easy to maintain.

Completed:

1. Custom model IDs and context windows can be stored in user configuration.

2. Added:

   zai model add
   zai model remove
   zai model info
   zai model test
   

3. Users can select a model ID independently from the provider transport.

4. Custom aliases are validated before saving.

5. Existing configuration is normalized to schema version 3.

6. Interactive completion and fallback include custom aliases.

7. Per-model timeout and retry settings apply to built-in and custom aliases.

8. Provider failures are normalized into authentication, quota/rate-limit, model-not-found, timeout, network, and malformed-response categories.

9. Successful responses display the selected alias, provider, and model ID.

Remaining:

1. Add explicit migrations for schema versions after version 3.

Suggested configuration:

{
  "default_model": "groq",
  "auto_fallback": true,
  "models": {
    "groq": {
      "provider": "groq",
      "model_id": "provider-model-id",
      "timeout": 60
    }
  }
}

Definition of done:

• Changing a model never requires editing Python source.
• Invalid provider/model configuration is rejected clearly.
• zai model test <name> verifies credentials and model availability.
• Old configuration files migrate automatically.

Context-management work completed alongside this phase:

• model-specific context limits;
• shared budgeting across chat, workflows, utilities, and agent mode;
• pinned project context, structured compaction, and bounded tool results;
• native tool-call/result pair preservation during compaction.

Phase 4: Large repository performance

Goal: keep repository understanding fast and bounded on large projects.

Implementation work:

1. Respect .gitignore, .ignore, and configurable ignore patterns.
2. Enforce file-size, repository-size, indexed-file, and scanned-file limits.
3. Cache repository maps using paths, modification metadata, and SHA-256 hashes.
4. Re-extract symbols only for changed files.
5. Prioritize source files and skip generated, binary, secret, and symlinked files.
6. Extract symbols from Python, JavaScript/TypeScript, Go, Rust, Java, C#, Ruby, PHP, Swift, and Kotlin.
7. Bound repository context using the active model's token budget.
8. Show indexing progress, cache activity, and skipped-file counts.

The incremental cache is stored at .zai/cache/repomap.json and should remain excluded from version control.

Relevant locations:

zai/core/repomap.py
zai/core/context.py
zai/cli/utilities.py

Performance targets:

• index 10,000 normal source files without loading every complete file;
• repeated map generation should use cache;
• default repository context should stay within the active model limit;
• generated directories and binary files should not enter prompts.

Definition of done:

• large deterministic fixtures cover bounded scans and incremental cache hits;
• cached scans avoid symbol extraction for unchanged files;
• context selection is deterministic and token bounded.

P1.5: Plugin and browser security

Goal: prevent implicit arbitrary-code execution, SSRF, and filesystem escape.

• Require a reviewed code fingerprint before loading local or pip plugins.
• Require validated manifests and declared permissions before code import.
• Confirm external installation and re-enabling.
• Invalidate plugin trust when local code or package records change.
• Require confirmation before every agent-triggered plugin tool call.
• Reject plugin names that can escape the plugin directory.
• Allow browser automation only for public credential-free HTTP(S) URLs.
• Block private, loopback, link-local, and unsafe redirected requests.
• Restrict screenshots to supported image files inside the current project.
• Add regression tests for plugin trust and browser network boundaries.

Phase 5: Session and undo management

Goal: make session history and filesystem recovery manageable rather than only automatic.

Available commands:

zai session list
zai session show <name>
zai session search <query>
zai session rename <old> <new>
zai session delete <name>
zai session export <name> --format md|json

zai undo list
zai undo show <id>
zai undo apply [id]
zai undo redo
zai undo clear

Completed:

• stable session IDs, titles, creation/update timestamps, and project metadata;
• top-level list, show, search, rename, delete, and export commands;
• interactive /resume, /session list|search|rename|delete;
• project-scoped listing/search and exact or unambiguous ID/name resolution;
• Markdown and JSON session export restricted to the selected project;
• stable undo action IDs, timestamps, summaries, and affected paths;
• inspectable and selectable multi-step undo;
• redo and history clearing;
• conflict detection before restoring files changed outside ZAI;
• bounded retention for session history and undo backups;
• project-local cache and recovery data excluded from Git.

Definition of done:

• users can inspect an operation before undoing it;
• multiple undo and redo operations are deterministic;
• stale/conflicting restores are blocked safely;
• sessions can be searched, exported, renamed, and deleted.

Phase 6: Stable release

Goal: publish a reproducible release that works from a clean installation.

Release procedure:

1. Run all non-live tests:

   python -m pytest -m "not integration" -q
   

2. Enforce coverage:

   python -m pytest -m "not integration" \
     --cov=zai --cov-report=term-missing --cov-fail-under=75
   

3. Run configured live tests.

4. Build and validate:

   python scripts/release_preflight.py
   python -m build
   python -m twine check dist/*
   python scripts/release_preflight.py --artifacts dist
   

5. Install the wheel into fresh Windows and Linux virtual environments.

6. Run smoke tests:

   zai --version
   zai --help
   zai model list
   zai repo map
   zai ask "Reply with ok"
   

7. Add a real repository URL to pyproject.toml.

8. Write CHANGELOG.md.

9. Bump the package version.

10. Run the Staged package release workflow with target=testpypi and install from TestPyPI.

11. Run the same workflow with target=pypi only after the TestPyPI wheel passes.

12. Create a signed Git tag and GitHub release.

The publish workflow additionally runs release preflight with --require-repository-url. Use target=testpypi for the staging publish and target=pypi for the real PyPI publish.

Definition of done:

• clean wheel installation succeeds on Windows and Linux;
• CI passes for every supported Python version;
• package data includes all built-in slash commands;
• TestPyPI installation passes smoke tests;
• release notes document features, limitations, and migration steps.

Recommended implementation order

Use this order for the next development cycle:

1. Live Groq validation, because Groq is the primary low-resource cloud option.
2. Terminal history, autocomplete, multiline input, and cancellation.
3. Configurable model IDs and zai model test.
4. Repository-map caching and .gitignore support.
5. Multi-step undo/redo and session management.
6. Fresh wheel installation and TestPyPI release.

Do not add unrelated feature commands until these phases are complete. The priority is predictable daily use, recoverability, and release quality.

License

MIT

zai_cli