Skip to content

CodeZ CLI is an interactive, offline first and AI-powered code assistant for your terminal. Features session memory, file reading with syntax highlighting, and a beautiful, customizable interface using Rich and prompt-toolkit. Perfect for developers who want smart code help right in the CLI without internet.

License

Notifications You must be signed in to change notification settings

sam43/code-z-cli

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ€– CodeZ CLI – Your Supercharged Offline Coding Buddy! πŸš€

Ever wished you had a coding assistant right in your terminal, one that respects your privacy and works offline? Meet CodeZ CLI! πŸŽ‰ It's a friendly, conversational code companion powered by local Large Language Models (LLMs) through Ollama, all jazzed up with slick Rich terminal visuals.

Whether you're learning a new language, need a quick code snippet, or want to understand complex code, CodeZ is here to help you out, right from your command line!


✨ Awesome Features ✨

  • πŸ—£οΈ Conversational REPL: Chat with your code and get context-aware responses.
  • ⚑ Lightning Fast: Instant interruption (ESC) and a super responsive UI.
  • ✍️ Smart Autocompletion: For commands and file paths, making typing a breeze.
  • πŸ’Ύ Session Savvy: Save your chats and resume them later. Never lose a brilliant thought!
  • πŸ“„ File Explorer: Read and display code or any file with beautiful syntax highlighting.
  • 🌈 Rich & Beautiful: Enjoy gorgeous markdown, code rendering, and panels in your terminal.
  • μ…Έ Shell Power: Run shell commands directly with ! (e.g., !ls -la).
  • 🌐 Web-Savvy (Optional): Enable a web search tool to pull in external knowledge.
  • 🧐 Code Analysis (Swift/C): Uses tree-sitter for deeper insights into Swift and C codebases (requires a small helper library).

There'sMore :

  • Model Management: Easily switch between local LLMs using /models or /model commands at any time.
  • Automatic Model Download: If no Ollama models are found, the CLI will prompt you to download and run the default model (qwen2.5-coder:1.5b-instruct).
  • Session Memory: Save, resume, and manage your coding conversations.
  • Extensible & Open Source: Built for privacy, hackability, and your workflow.

πŸš€ Getting Started: Your First Chat in Minutes! πŸš€

Ready to team up with CodeZ? Here’s how:

Step 1: Get Your Local LLM Brain 🧠 (Install Ollama)

CodeZ CLI uses Ollama to run powerful language models locally on your machine. This means your code and conversations stay private!

  • Head over to ollama.com/download and install it for your operating system (macOS, Linux, Windows).
  • Once installed, pull your favorite model. We recommend starting with one like llama3 or mistral:
    ollama pull llama3
    (Make sure Ollama is running after installation!)

Step 2: Install CodeZ CLI πŸ’»

This is as easy as pie! πŸ₯§

pip install codez-cli
  • For macOS users: If you see an error about an "externally managed environment," it's best to use a virtual environment:

    python3 -m venv ~/codez-venv
    source ~/codez-venv/bin/activate
    pip install codez-cli
  • What about tree-sitter and ios_lang.so?

    • The pip install command automatically installs tree-sitter, a cool library CodeZ uses for advanced code parsing.
    • For enhanced understanding of Swift and C code, CodeZ uses a special helper library (ios_lang.so).
      • For most users: The core features of CodeZ work perfectly without this. If this specific library isn't pre-built for your system yet, you'll still have a fantastic experience! We're working on making this seamless.
      • For developers: If you want to enable this or contribute, you can build it easily! (See the "For Developers πŸ€“" section below).

πŸ’¬ Let's Chat! - Using CodeZ CLI πŸ’¬

You're all set! Time to start your first conversation:

Launch CodeZ:

Just type this in your terminal:

codez chat

You should see a friendly welcome message! Now, just type your questions or commands.

Quick File Explanation:

Want to quickly understand a file or function? Use the explain command:

codez explain path/to/your/file.py
codez explain path/to/your/file.py --function my_function

Essential Commands (Your Chat Toolkit):

  • Ask anything: Just type your question and press Enter.
    >>> How do I write a "Hello, World!" in Python?
    
  • Read a file: Get CodeZ to read a file for you.
    >>> /read path/to/your/file.py
    
  • End your chat: Ready to wrap up?
    >>> /endit
    
    (This saves your conversation to the sessions/ directory in your project root – how cool is that?!)
  • Clear the screen: Need a fresh slate?
    >>> /clear  # or just 'clr'
    
  • Choose your LLM: See available models or switch to a new one.
    >>> /models
    >>> /model -u current_model new_model
    
  • Toggle tools: Enable or disable features like web search.
    >>> /tools
    
  • Run shell commands: Access your system shell.
    >>> !ls -l
    >>> !git status
    
  • Need help? A handy reminder of commands.
    >>> /helpme
    

Quick Example:

>>> What's the syntax for a for-loop in JavaScript?
πŸ€– CodeZ: [Provides a clear explanation and example]
>>> /read ./my_script.js
πŸ€– CodeZ: [Displays your script with syntax highlighting] Okay, I've read my_script.js. What would you like to do with it?
>>> Can you explain the main function in this script?
πŸ€– CodeZ: [Analyzes and explains]
>>> /endit

πŸ’ͺ Superpowers (Advanced Features) πŸ’ͺ

  • 🧠 Contextual Memory: CodeZ remembers your conversation (within a configurable token budget) to give you smarter, more relevant answers over time. Oldest parts of the chat are gracefully trimmed if needed.
    • Set your token budget via the CODEZ_MAX_TOKEN_BUDGET environment variable or in the config.
    • Stateless mode is also available: codez --no-memory
  • πŸ—‚οΈ Session Management: Your conversations are automatically saved! You can even load previous sessions to pick up where you left off or provide more context.
    • Session files live in the sessions/ directory (usually in your project's root, or where you run codez).
  • βš™οΈ Configuration: CodeZ stores its settings (like your preferred model) in a user-friendly location:
    • macOS/Linux: ~/.config/codez/config.json
    • Windows: %APPDATA%\codez\config.json (Thanks to the platformdirs library!)

βœ… Requirements Checklist βœ…

  • Python 3.8 or newer
  • Ollama installed and running with at least one model (e.g., ollama pull llama3)
  • The Python packages rich, prompt_toolkit, platformdirs, and tree-sitter (these are installed automatically when you pip install codez-cli).

πŸ€“ For Developers & Contributors πŸ€“

Want to peek under the hood, add new features, or fix a bug? Awesome!

Setting Up Your Dev Environment:

  1. Clone the repo:
    git clone https://github.com/sam43/code-z-cli.git
    cd code-z-cli
  2. Create a virtual environment (recommended):
    python3 -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate
  3. Install dependencies (including dev tools):
    pip install -r requirements.txt
    # For editable mode, if you plan to make changes to CodeZ itself:
    pip install -e .
  4. Build the ios_lang.so (for Swift/C parsing): This step is needed if you want to work on or test the Swift/C advanced parsing features. It requires a C compiler.
    python build_language_lib.py
    This will create build/ios_lang.so. The app looks for it at ./build/ios_lang.so relative to where core/parser.py is.

Running from Source:

After setup, you can run CodeZ directly:

python -m codechat
# or
python __main__.py

Running Tests:

We use pytest for testing.

# Install pytest if you haven't already (it's in requirements.txt)
# pip install pytest
pytest
# or for more verbose output / specific tests:
PYTHONPATH=. pytest -s tests/core/test_llm_interactive.py

Project Structure Overview:

code-z-cli/
β”œβ”€β”€ codechat/             # Main application package
β”‚   β”œβ”€β”€ __main__.py       # Main entry point for `python -m codechat`
β”‚   β”œβ”€β”€ interface/        # CLI interface logic
β”‚   β”œβ”€β”€ domain/           # Core domain models (e.g., conversation)
β”‚   β”œβ”€β”€ data/             # Data handling (e.g., session repository)
β”‚   └── docs/             # Contains TECHNICAL.md
β”œβ”€β”€ core/                 # Core logic (LLM interaction, parsing, REPL)
β”‚   β”œβ”€β”€ model.py          # LLM interaction via Ollama
β”‚   β”œβ”€β”€ parser.py         # Code parsing (uses tree-sitter)
β”‚   β”œβ”€β”€ repl.py           # REPL implementation (though CLI() is now the entry)
β”‚   └── ...
β”œβ”€β”€ build/                # Output for compiled libraries like ios_lang.so
β”œβ”€β”€ sessions/             # Stores user conversation sessions (created at runtime)
β”œβ”€β”€ vendor/               # tree-sitter language grammars (used by build_language_lib.py)
β”œβ”€β”€ tests/                # Unit tests
β”œβ”€β”€ build_language_lib.py # Script to build the tree-sitter language library
β”œβ”€β”€ setup.py              # Packaging script
β”œβ”€β”€ pyproject.toml        # Modern Python packaging configuration
β”œβ”€β”€ requirements.txt      # Development dependencies
β”œβ”€β”€ README.md             # This awesome file!
└── LICENSE               # Apache 2.0 License
  • Note on packaging: venv/, sessions/, and build/ directories should not be included in the distributed PyPI package. vendor/ is needed to build ios_lang.so but isn't strictly a runtime dependency for the app if ios_lang.so is pre-built.

Want to dive deeper?

Check out the Technical Documentation for more architectural insights!


🀝 Join the Adventure! (Contributing) 🀝

CodeZ CLI is an open-source project, and we welcome contributions of all kinds! Whether it's reporting a bug, suggesting a feature, improving documentation, or writing code, your help is appreciated.

  • Issues: Found a bug or have an idea? Open an issue!
  • Pull Requests: Got a fix or a new feature? Submit a Pull Request!

Let's make CodeZ CLI even more amazing together!


πŸ“œ License πŸ“œ

CodeZ CLI is licensed under the Apache 2.0 License. See the LICENSE file for details.


Happy Coding with your new AI buddy! If you love CodeZ, don't forget to ⭐ the repo!

About

CodeZ CLI is an interactive, offline first and AI-powered code assistant for your terminal. Features session memory, file reading with syntax highlighting, and a beautiful, customizable interface using Rich and prompt-toolkit. Perfect for developers who want smart code help right in the CLI without internet.

Topics

Resources

License

Stars

Watchers

Forks

Contributors 3

  •  
  •  
  •