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!
- π£οΈ 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).
- 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.
Ready to team up with CodeZ? Hereβs how:
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
ormistral
:(Make sure Ollama is running after installation!)ollama pull llama3
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
andios_lang.so
?- The
pip install
command automatically installstree-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).
- The
You're all set! Time to start your first conversation:
Just type this in your terminal:
codez chat
You should see a friendly welcome message! Now, just type your questions or commands.
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
- 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?
(This saves your conversation to the
>>> /endit
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
>>> 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
- π§ 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
- Set your token budget via the
- ποΈ 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 runcodez
).
- Session files live in the
- βοΈ 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!)
- macOS/Linux:
- 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
, andtree-sitter
(these are installed automatically when youpip install codez-cli
).
Want to peek under the hood, add new features, or fix a bug? Awesome!
- Clone the repo:
git clone https://github.com/sam43/code-z-cli.git cd code-z-cli
- Create a virtual environment (recommended):
python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
- 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 .
- 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.This will createpython build_language_lib.py
build/ios_lang.so
. The app looks for it at./build/ios_lang.so
relative to wherecore/parser.py
is.
After setup, you can run CodeZ directly:
python -m codechat
# or
python __main__.py
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
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/
, andbuild/
directories should not be included in the distributed PyPI package.vendor/
is needed to buildios_lang.so
but isn't strictly a runtime dependency for the app ifios_lang.so
is pre-built.
Check out the Technical Documentation for more architectural insights!
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!
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!