codemaster-cli 2.2.0__py3-none-any.whl

codemaster_cli-2.2.0.dist-info/METADATA

@@ -0,0 +1,645 @@
+Metadata-Version: 2.4
+Name: codemaster-cli
+Version: 2.2.0
+Summary: CLI coding assistant with local LLM support via Ollama
+Project-URL: Homepage, https://github.com/marshal0004/CodeMaster
+Project-URL: Repository, https://github.com/marshal0004/CodeMaster
+Project-URL: Issues, https://github.com/marshal0004/CodeMaster/issues
+Project-URL: Documentation, https://github.com/marshal0004/CodeMaster#readme
+Author: codeMaster Contributors
+License: Apache-2.0
+Keywords: ai,cli,coding-assistant,developer-tools,llm,local-llm,ollama
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: agent-client-protocol==0.8.0
+Requires-Dist: anyio>=4.12.0
+Requires-Dist: cryptography<=46.0.3,>=44.0.0
+Requires-Dist: gitpython>=3.1.46
+Requires-Dist: giturlparse>=0.14.0
+Requires-Dist: google-auth>=2.0.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: keyring>=25.6.0
+Requires-Dist: mcp>=1.14.0
+Requires-Dist: mistralai==1.9.11
+Requires-Dist: packaging>=24.1
+Requires-Dist: pexpect>=4.9.0
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: pydantic>=2.12.4
+Requires-Dist: pyperclip>=1.11.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: requests>=2.20.0
+Requires-Dist: rich>=14.0.0
+Requires-Dist: textual-speedups>=0.2.1
+Requires-Dist: textual>=1.0.0
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: tree-sitter-bash>=0.25.1
+Requires-Dist: tree-sitter>=0.25.2
+Requires-Dist: watchfiles>=1.1.1
+Requires-Dist: zstandard>=0.25.0
+Description-Content-Type: text/markdown
+
+# codeMaster
+
+[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/release/python-3120/)
+
+
+
+
+**Open-source CLI coding assistant with local LLM support.**
+
+codeMaster is a command-line coding assistant that works with both cloud-based and local LLM models (via Ollama). It provides a conversational interface to your codebase, allowing you to use natural language to explore, modify, and interact with your projects through a powerful set of tools.
+
+> [!NOTE]
+> codeMaster works on Windows, but we officially support and target UNIX environments.
+
+### Installation
+
+**Using pip**
+
+```bash
+pip install -e .
+```
+
+**Using uv**
+
+```bash
+uv pip install -e .
+```
+
+### Quick Setup
+
+After installation, codeMaster will be available via the `codemaster` command.
+
+## Table of Contents
+
+- [Features](#features)
+  - [Built-in Agents](#built-in-agents)
+  - [Subagents and Task Delegation](#subagents-and-task-delegation)
+  - [Interactive User Questions](#interactive-user-questions)
+- [Terminal Requirements](#terminal-requirements)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+  - [Interactive Mode](#interactive-mode)
+  - [Trust Folder System](#trust-folder-system)
+  - [Programmatic Mode](#programmatic-mode)
+- [Slash Commands](#slash-commands)
+  - [Built-in Slash Commands](#built-in-slash-commands)
+  - [Custom Slash Commands via Skills](#custom-slash-commands-via-skills)
+- [Skills System](#skills-system)
+  - [Creating Skills](#creating-skills)
+  - [Skill Discovery](#skill-discovery)
+  - [Managing Skills](#managing-skills)
+- [Configuration](#configuration)
+  - [Configuration File Location](#configuration-file-location)
+  - [API Key Configuration](#api-key-configuration)
+  - [Custom System Prompts](#custom-system-prompts)
+  - [Custom Agent Configurations](#custom-agent-configurations)
+  - [Tool Management](#tool-management)
+  - [MCP Server Configuration](#mcp-server-configuration)
+  - [Session Management](#session-management)
+  - [Update Settings](#update-settings)
+  - [Custom codeMaster Home Directory](#custom-codemaster-home-directory)
+- [Editors/IDEs](#editorsides)
+- [Resources](#resources)
+- [Data collection & usage](#data-collection--usage)
+- [License](#license)
+
+## Features
+
+- **Interactive Chat**: A conversational AI agent that understands your requests and breaks down complex tasks.
+- **Local & Cloud LLM Support**: Works with Ollama (local models) and cloud APIs (Mistral, OpenAI, etc.)
+- **Powerful Toolset**: A suite of tools for file manipulation, code searching, version control, and command execution, right from the chat prompt.
+  - Read, write, and patch files (`read_file`, `write_file`, `search_replace`).
+  - Execute shell commands in a stateful terminal (`bash`).
+  - Recursively search code with `grep` (with `ripgrep` support).
+  - Manage a `todo` list to track the agent's work.
+  - Ask interactive questions to gather user input (`ask_user_question`).
+  - Delegate tasks to subagents for parallel work (`task`).
+- **Project-Aware Context**: codeMaster automatically scans your project's file structure and Git status to provide relevant context to the agent, improving its understanding of your codebase.
+- **Advanced CLI Experience**: Built with modern libraries for a smooth and efficient workflow.
+  - Autocompletion for slash commands (`/`) and file paths (`@`).
+  - Persistent command history.
+  - Beautiful Themes.
+- **Highly Configurable**: Customize models, providers, tool permissions, and UI preferences through a simple `config.toml` file.
+- **Safety First**: Features tool execution approval.
+- **Multiple Built-in Agents**: Choose from different agent profiles tailored for specific workflows.
+
+### Built-in Agents
+
+codeMaster comes with several built-in agent profiles, each designed for different use cases:
+
+- **`default`**: Standard agent that requires approval for tool executions. Best for general use.
+- **`plan`**: Read-only agent for exploration and planning. Auto-approves safe tools like `grep` and `read_file`.
+- **`accept-edits`**: Auto-approves file edits only (`write_file`, `search_replace`). Useful for code refactoring.
+- **`auto-approve`**: Auto-approves all tool executions. Use with caution.
+
+Use the `--agent` flag to select a different agent:
+
+```bash
+codemaster --agent plan
+```
+
+### Subagents and Task Delegation
+
+codeMaster supports subagents for delegating tasks. Subagents run independently and can perform specialized work without user interaction, preventing the context from being overloaded.
+
+The `task` tool allows the agent to delegate work to subagents:
+
+```
+> Can you explore the codebase structure while I work on something else?
+
+🤖 I'll use the task tool to delegate this to the explore subagent.
+
+> task(task="Analyze the project structure and architecture", agent="explore")
+```
+
+Create custom subagents by adding `agent_type = "subagent"` to your agent configuration. codeMaster comes with a built-in subagent called `explore`, a read-only subagent for codebase exploration used internally for delegation.
+
+### Interactive User Questions
+
+The `ask_user_question` tool allows the agent to ask you clarifying questions during its work. This enables more interactive and collaborative workflows.
+
+```
+> Can you help me refactor this function?
+
+🤖 I need to understand your requirements better before proceeding.
+
+> ask_user_question(questions=[{
+    "question": "What's the main goal of this refactoring?",
+    "options": [
+        {"label": "Performance", "description": "Make it run faster"},
+        {"label": "Readability", "description": "Make it easier to understand"},
+        {"label": "Maintainability", "description": "Make it easier to modify"}
+    ]
+}])
+```
+
+The agent can ask multiple questions at once, displayed as tabs. Each question supports 2-4 options plus an automatic "Other" option for free text responses.
+
+## Terminal Requirements
+
+codeMaster's interactive interface requires a modern terminal emulator. Recommended terminal emulators include:
+
+- **WezTerm** (cross-platform)
+- **Alacritty** (cross-platform)
+- **Ghostty** (Linux and macOS)
+- **Kitty** (Linux and macOS)
+
+Most modern terminals should work, but older or minimal terminal emulators may have display issues.
+
+## Quick Start
+
+1. Navigate to your project's root directory:
+
+   ```bash
+   cd /path/to/your/project
+   ```
+
+2. Run codeMaster:
+
+   ```bash
+   codemaster
+   ```
+
+3. If this is your first time running codeMaster, it will:
+
+   - Create a default configuration file at `~/.codemaster/config.toml`
+   - Prompt you to configure your LLM provider (Ollama local or cloud API)
+   - Save your configuration for future use
+
+   Alternatively, you can configure your setup using `codemaster --setup`.
+
+4. Start interacting with the agent!
+
+   ```
+   > Can you find all instances of the word "TODO" in the project?
+
+   🤖 The user wants to find all instances of "TODO". The `grep` tool is perfect for this. I will use it to search the current directory.
+
+   > grep(pattern="TODO", path=".")
+
+   ... (grep tool output) ...
+
+   🤖 I found the following "TODO" comments in your project.
+   ```
+
+## Usage
+
+### Interactive Mode
+
+Simply run `codemaster` to enter the interactive chat loop.
+
+- **Multi-line Input**: Press `Ctrl+J` or `Shift+Enter` for select terminals to insert a newline.
+- **File Paths**: Reference files in your prompt using the `@` symbol for smart autocompletion (e.g., `> Read the file @src/agent.py`).
+- **Shell Commands**: Prefix any command with `!` to execute it directly in your shell, bypassing the agent (e.g., `> !ls -l`).
+- **External Editor**: Press `Ctrl+G` to edit your current input in an external editor.
+- **Tool Output Toggle**: Press `Ctrl+O` to toggle the tool output view.
+- **Todo View Toggle**: Press `Ctrl+T` to toggle the todo list view.
+- **Auto-Approve Toggle**: Press `Shift+Tab` to toggle auto-approve mode on/off.
+
+You can start codeMaster with a prompt using the following command:
+
+```bash
+codemaster "Refactor the main function in cli/main.py to be more modular."
+```
+
+**Note**: The `--auto-approve` flag automatically approves all tool executions without prompting. In interactive mode, you can also toggle auto-approve on/off using `Shift+Tab`.
+
+### Trust Folder System
+
+codeMaster includes a trust folder system to ensure you only run the agent in directories you trust. When you first run codeMaster in a new directory which contains a `.codemaster` subfolder, it may ask you to confirm whether you trust the folder.
+
+Trusted folders are remembered for future sessions. You can manage trusted folders through its configuration file `~/.codemaster/trusted_folders.toml`.
+
+This safety feature helps prevent accidental execution in sensitive directories.
+
+### Programmatic Mode
+
+You can run codeMaster non-interactively by piping input or using the `--prompt` flag. This is useful for scripting.
+
+```bash
+codemaster --prompt "Refactor the main function in cli/main.py to be more modular."
+```
+
+By default, it uses `auto-approve` mode.
+
+#### Programmatic Mode Options
+
+When using `--prompt`, you can specify additional options:
+
+- **`--max-turns N`**: Limit the maximum number of assistant turns. The session will stop after N turns.
+- **`--max-price DOLLARS`**: Set a maximum cost limit in dollars. The session will be interrupted if the cost exceeds this limit.
+- **`--enabled-tools TOOL`**: Enable specific tools. In programmatic mode, this disables all other tools. Can be specified multiple times. Supports exact names, glob patterns (e.g., `bash*`), or regex with `re:` prefix (e.g., `re:^serena_.*$`).
+- **`--output FORMAT`**: Set the output format. Options:
+  - `text` (default): Human-readable text output
+  - `json`: All messages as JSON at the end
+  - `streaming`: Newline-delimited JSON per message
+
+Example:
+
+```bash
+codemaster --prompt "Analyze the codebase" --max-turns 5 --max-price 1.0 --output json
+```
+
+## Slash Commands
+
+Use slash commands for meta-actions and configuration changes during a session.
+
+### Built-in Slash Commands
+
+codeMaster provides several built-in slash commands. Use slash commands by typing them in the input box:
+
+```
+> /help
+```
+
+### Custom Slash Commands via Skills
+
+You can define your own slash commands through the skills system. Skills are reusable components that extend codeMaster's functionality.
+
+To create a custom slash command:
+
+1. Create a skill directory with a `SKILL.md` file
+2. Set `user-invocable = true` in the skill metadata
+3. Define the command logic in your skill
+
+Example skill metadata:
+
+```markdown
+---
+name: my-skill
+description: My custom skill with slash commands
+user-invocable: true
+---
+```
+
+Custom slash commands appear in the autocompletion menu alongside built-in commands.
+
+## Skills System
+
+codeMaster's skills system allows you to extend functionality through reusable components. Skills can add new tools, slash commands, and specialized behaviors.
+
+codeMaster follows the [Agent Skills specification](https://agentskills.io/specification) for skill format and structure.
+
+### Creating Skills
+
+Skills are defined in directories with a `SKILL.md` file containing metadata in YAML frontmatter. For example, `~/.codemaster/skills/code-review/SKILL.md`:
+
+```markdown
+---
+name: code-review
+description: Perform automated code reviews
+license: MIT
+compatibility: Python 3.12+
+user-invocable: true
+allowed-tools:
+  - read_file
+  - grep
+  - ask_user_question
+---
+
+# Code Review Skill
+
+This skill helps analyze code quality and suggest improvements.
+```
+
+### Skill Discovery
+
+codeMaster discovers skills from multiple locations:
+
+1. **Custom paths**: Configured in `config.toml` via `skill_paths`
+2. **Standard Agent Skills path** (project root, trusted folders only): `.agents/skills/` — [Agent Skills](https://agentskills.io) standard
+3. **Local project skills** (project root, trusted folders only): `.codemaster/skills/` in your project
+4. **Global skills directory**: `~/.codemaster/skills/`
+
+```toml
+skill_paths = ["/path/to/custom/skills"]
+```
+
+### Managing Skills
+
+Enable or disable skills using patterns in your configuration:
+
+```toml
+# Enable specific skills
+enabled_skills = ["code-review", "test-*"]
+
+# Disable specific skills
+disabled_skills = ["experimental-*"]
+```
+
+Skills support the same pattern matching as tools (exact names, glob patterns, and regex).
+
+## Configuration
+
+### Configuration File Location
+
+codeMaster is configured via a `config.toml` file. It looks for this file first in `./.codemaster/config.toml` and then falls back to `~/.codemaster/config.toml`.
+
+### API Key Configuration
+
+To use codeMaster, you'll need a Mistral API key. You can obtain one by signing up at [https://console.mistral.ai](https://console.mistral.ai).
+
+You can configure your API key using `codemaster --setup`, or through one of the methods below.
+
+codeMaster supports multiple ways to configure your API keys:
+
+1. **Interactive Setup (Recommended for first-time users)**: When you run codeMaster for the first time or if your API key is missing, codeMaster will prompt you to enter it. The key will be securely saved to `~/.codemaster/.env` for future sessions.
+
+2. **Environment Variables**: Set your API key as an environment variable:
+
+   ```bash
+   export MISTRAL_API_KEY="your_mistral_api_key"
+   ```
+
+3. **`.env` File**: Create a `.env` file in `~/.codemaster/` and add your API keys:
+
+   ```bash
+   MISTRAL_API_KEY=your_mistral_api_key
+   ```
+
+   codeMaster automatically loads API keys from `~/.codemaster/.env` on startup. Environment variables take precedence over the `.env` file if both are set.
+
+**Note**: The `.env` file is specifically for API keys and other provider credentials. General codeMaster configuration should be done in `config.toml`.
+
+### Custom System Prompts
+
+You can create custom system prompts to replace the default one (`prompts/cli.md`). Create a markdown file in the `~/.codemaster/prompts/` directory with your custom prompt content.
+
+To use a custom system prompt, set the `system_prompt_id` in your configuration to match the filename (without the `.md` extension):
+
+```toml
+# Use a custom system prompt
+system_prompt_id = "my_custom_prompt"
+```
+
+This will load the prompt from `~/.codemaster/prompts/my_custom_prompt.md`.
+
+### Custom Agent Configurations
+
+You can create custom agent configurations for specific use cases (e.g., red-teaming, specialized tasks) by adding agent-specific TOML files in the `~/.codemaster/agents/` directory.
+
+To use a custom agent, run codeMaster with the `--agent` flag:
+
+```bash
+codemaster --agent my_custom_agent
+```
+
+codeMaster will look for a file named `my_custom_agent.toml` in the agents directory and apply its configuration.
+
+Example custom agent configuration (`~/.codemaster/agents/redteam.toml`):
+
+```toml
+# Custom agent configuration for red-teaming
+active_model = "devstral-2"
+system_prompt_id = "redteam"
+
+# Disable some tools for this agent
+disabled_tools = ["search_replace", "write_file"]
+
+# Override tool permissions for this agent
+[tools.bash]
+permission = "always"
+
+[tools.read_file]
+permission = "always"
+```
+
+Note: This implies that you have set up a redteam prompt named `~/.codemaster/prompts/redteam.md`.
+
+### Tool Management
+
+#### Enable/Disable Tools with Patterns
+
+You can control which tools are active using `enabled_tools` and `disabled_tools`.
+These fields support exact names, glob patterns, and regular expressions.
+
+Examples:
+
+```toml
+# Only enable tools that start with "serena_" (glob)
+enabled_tools = ["serena_*"]
+
+# Regex (prefix with re:) — matches full tool name (case-insensitive)
+enabled_tools = ["re:^serena_.*$"]
+
+# Disable a group with glob; everything else stays enabled
+disabled_tools = ["mcp_*", "grep"]
+```
+
+Notes:
+
+- MCP tool names use underscores, e.g., `serena_list` not `serena.list`.
+- Regex patterns are matched against the full tool name using fullmatch.
+
+### MCP Server Configuration
+
+You can configure MCP (Model Context Protocol) servers to extend codeMaster's capabilities. Add MCP server configurations under the `mcp_servers` section:
+
+```toml
+# Example MCP server configurations
+[[mcp_servers]]
+name = "my_http_server"
+transport = "http"
+url = "http://localhost:8000"
+headers = { "Authorization" = "Bearer my_token" }
+api_key_env = "MY_API_KEY_ENV_VAR"
+api_key_header = "Authorization"
+api_key_format = "Bearer {token}"
+
+[[mcp_servers]]
+name = "my_streamable_server"
+transport = "streamable-http"
+url = "http://localhost:8001"
+headers = { "X-API-Key" = "my_api_key" }
+
+[[mcp_servers]]
+name = "fetch_server"
+transport = "stdio"
+command = "uvx"
+args = ["mcp-server-fetch"]
+env = { "DEBUG" = "1", "LOG_LEVEL" = "info" }
+```
+
+Supported transports:
+
+- `http`: Standard HTTP transport
+- `streamable-http`: HTTP transport with streaming support
+- `stdio`: Standard input/output transport (for local processes)
+
+Key fields:
+
+- `name`: A short alias for the server (used in tool names)
+- `transport`: The transport type
+- `url`: Base URL for HTTP transports
+- `headers`: Additional HTTP headers
+- `api_key_env`: Environment variable containing the API key
+- `command`: Command to run for stdio transport
+- `args`: Additional arguments for stdio transport
+- `startup_timeout_sec`: Timeout in seconds for the server to start and initialize (default 10s)
+- `tool_timeout_sec`: Timeout in seconds for tool execution (default 60s)
+- `env`: Environment variables to set for the MCP server of transport type stdio
+
+MCP tools are named using the pattern `{server_name}_{tool_name}` and can be configured with permissions like built-in tools:
+
+```toml
+# Configure permissions for specific MCP tools
+[tools.fetch_server_get]
+permission = "always"
+
+[tools.my_http_server_query]
+permission = "ask"
+```
+
+MCP server configurations support additional features:
+
+- **Environment variables**: Set environment variables for MCP servers
+- **Custom timeouts**: Configure startup and tool execution timeouts
+
+Example with environment variables and timeouts:
+
+```toml
+[[mcp_servers]]
+name = "my_server"
+transport = "http"
+url = "http://localhost:8000"
+env = { "DEBUG" = "1", "LOG_LEVEL" = "info" }
+startup_timeout_sec = 15
+tool_timeout_sec = 120
+```
+
+### Session Management
+
+#### Session Continuation and Resumption
+
+codeMaster supports continuing from previous sessions:
+
+- **`--continue`** or **`-c`**: Continue from the most recent saved session
+- **`--resume SESSION_ID`**: Resume a specific session by ID (supports partial matching)
+
+```bash
+# Continue from last session
+codemaster --continue
+
+# Resume specific session
+codemaster --resume abc123
+```
+
+Session logging must be enabled in your configuration for these features to work.
+
+#### Working Directory Control
+
+Use the `--workdir` option to specify a working directory:
+
+```bash
+codemaster --workdir /path/to/project
+```
+
+This is useful when you want to run codeMaster from a different location than your current directory.
+
+### Update Settings
+
+#### Auto-Update
+
+codeMaster includes an automatic update feature that keeps your installation current. This is enabled by default.
+
+To disable auto-updates, add this to your `config.toml`:
+
+```toml
+enable_auto_update = false
+```
+
+### Custom codeMaster Home Directory
+
+By default, codeMaster stores its configuration in `~/.codemaster/`. You can override this by setting the `VIBE_HOME` environment variable:
+
+```bash
+export VIBE_HOME="/path/to/custom/codemaster/home"
+```
+
+This affects where codeMaster looks for:
+
+- `config.toml` - Main configuration
+- `.env` - API keys
+- `agents/` - Custom agent configurations
+- `prompts/` - Custom system prompts
+- `tools/` - Custom tools
+- `logs/` - Session logs
+
+## Editors/IDEs
+
+codeMaster can be used in text editors and IDEs that support [Agent Client Protocol](https://agentclientprotocol.com/overview/clients). See the [ACP Setup documentation](docs/acp-setup.md) for setup instructions for various editors and IDEs.
+
+## Resources
+
+- [CHANGELOG](CHANGELOG.md) - See what's new in each version
+- [CONTRIBUTING](CONTRIBUTING.md) - Guidelines for feature requests, feedback and bug reports
+
+## Data collection & usage
+
+Use of codeMaster is subject to our [Privacy Policy](https://legal.mistral.ai/terms/privacy-policy) and may include the collection and processing of data related to your use of the service, such as usage data, to operate, maintain, and improve codeMaster. You can disable telemetry in your `config.toml` by setting `enable_telemetry = false`.
+
+## License
+
+Copyright 2025 codeMaster AI
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the [LICENSE](LICENSE) file for the full license text.