Metadata-Version: 2.4
Name: zai-cli
Version: 0.1.3
Summary: Your personal AI CLI — free, fast, and smart
License-Expression: MIT
Project-URL: Homepage, https://github.com/HumaizaNaz/zai_cli
Project-URL: Repository, https://github.com/HumaizaNaz/zai_cli
Project-URL: Issues, https://github.com/HumaizaNaz/zai_cli/issues
Project-URL: Changelog, https://github.com/HumaizaNaz/zai_cli/blob/main/CHANGELOG.md
Keywords: ai,cli,assistant,gemini,groq,llm
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: prompt-toolkit>=3.0.48
Requires-Dist: pathspec>=0.12.1
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0.0; extra == "gemini"
Provides-Extra: groq
Requires-Dist: groq>=0.11.0; extra == "groq"
Provides-Extra: cerebras
Requires-Dist: cerebras-cloud-sdk>=1.0.0; extra == "cerebras"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40.0; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: all
Requires-Dist: google-genai>=1.0.0; extra == "all"
Requires-Dist: groq>=0.11.0; extra == "all"
Requires-Dist: cerebras-cloud-sdk>=1.0.0; extra == "all"
Requires-Dist: anthropic>=0.40.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.12.0; extra == "dev"
Requires-Dist: mypy>=1.16.0; extra == "dev"
Requires-Dist: pip-audit>=2.9.0; extra == "dev"
Requires-Dist: tomli>=2.2.1; python_version < "3.11" and extra == "dev"
Dynamic: license-file

# 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

```bash
pip install zai-cli
zai setup
```

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

For local development:

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

Optional live service checks:

```bash
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

```bash
# 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`.

## Main commands

```text
zai                         Start the interactive project assistant
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 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:

```bash
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:

```text
/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:

```text
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:

```text
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:

```text
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:

```bash
zai hook add PreToolUse "python validate_tool.py"
```

## Browser support

Browser commands require Playwright:

```bash
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:

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

Commands:

```bash
# 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:

   ```text
   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:

```json
{
  "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. [x] Respect `.gitignore`, `.ignore`, and configurable ignore patterns.
2. [x] Enforce file-size, repository-size, indexed-file, and scanned-file limits.
3. [x] Cache repository maps using paths, modification metadata, and SHA-256 hashes.
4. [x] Re-extract symbols only for changed files.
5. [x] Prioritize source files and skip generated, binary, secret, and symlinked files.
6. [x] Extract symbols from Python, JavaScript/TypeScript, Go, Rust, Java, C#,
   Ruby, PHP, Swift, and Kotlin.
7. [x] Bound repository context using the active model's token budget.
8. [x] 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:

```text
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:

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

### P1.5: Plugin and browser security

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

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

```text
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:

- [x] users can inspect an operation before undoing it;
- [x] multiple undo and redo operations are deterministic;
- [x] stale/conflicting restores are blocked safely;
- [x] 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:

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

2. Enforce coverage:

   ```bash
   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:

   ```bash
   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:

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

7. [x] Add a real repository URL to `pyproject.toml`.
8. [x] 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
