zai-cli 0.1.0

Your personal AI CLI — free, fast, and smart

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.

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
zai setup

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

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

# 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

Main commands

zai                         Start the interactive project assistant
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 and model availability
zai memory show             Show last task metadata
zai memory projects         List remembered projects
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
/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.

Context management

All chat, workflow, utility, and agent requests use the same 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;
• older turns are compacted into a structured summary while recent turns stay verbatim;
• context usage uses a conservative shared token estimate, while provider response usage is retained where the SDK reports it.

This replaces the previous fixed 100k limit and manual last-message truncation.

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.

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