tunacode-cli 0.0.69__tar.gz → 0.0.71__tar.gz

tunacode_cli-0.0.71/.claude/commands/phaser.md

@@ -0,0 +1,143 @@
+# Phase Planner Shortcut
+
+A systematic workflow command for implementing features in phases with automatic commits after each subphase using a git worktree.
+
+## Command: `/phase-planner`
+
+### Purpose
+Implements features through structured phases, with automatic linting, typechecking, building, and committing after each subphase completion using a git worktree.
+
+**CRITICAL REQUIREMENTS:**
+- **MUST use git worktree** for implementation
+- Worktree name = issue name (e.g., `issue-1`)
+- Create worktree in same directory as issue file
+- Commit after EACH subphase completion
+- **NEVER merge to main branch**
+- **NEVER push outside the worktree**
+- Violation of these rules will result in PUNISHMENT
+
+### Workflow Pattern
+```
+Phase 1
+├── 1.1: [First subphase]
+│   ├── Implement
+│   ├── Lint & Typecheck (new code only)
+│   ├── Build
+│   └── Commit if successful
+├── 1.2: [Second subphase]
+│   ├── Implement
+│   ├── Lint & Typecheck (new code only)
+│   ├── Build
+│   └── Commit if successful
+└── 1.3: [Third subphase]
+    ├── Implement
+    ├── Lint & Typecheck (new code only)
+    ├── Build
+    └── Commit if successful
+```
+
+### Command Implementation
+
+```yaml
+/phase-planner [feature-description] [issue-name]
+
+# Worktree Setup (MANDATORY)
+1. Identify issue name (e.g., "issue-1")
+2. Create git worktree:
+   - !git worktree add ./[issue-name] -b [issue-name]
+   - cd into worktree directory
+3. All work MUST happen in this worktree
+
+# Phase Planning
+1. Analyze the feature request
+2. Break down into phases (usually 3-5 phases)
+3. Each phase has 3-5 subphases
+4. Create todo list for Phase 1 only
+
+# Phase 1 Execution Loop
+For each subphase (1.1, 1.2, 1.3...):
+  1. Mark subphase as in_progress
+  2. Implement the subphase functionality
+  3. Run lint on new/modified files only:
+     - @package.json check for lint command
+     - !npm run lint -- [specific-files]
+  4. Run typecheck on new/modified files only:
+     - @package.json check for typecheck command
+     - !npm run typecheck -- [specific-files]
+  5. If lint/typecheck pass:
+     - !npm run build (if exists)
+     - If build passes:
+       - !git add [modified-files]
+       - !git commit -m "feat(phase-1.x): [description]"
+  6. Mark subphase as completed
+  7. Continue to next subphase
+
+# Documentation Update
+After all Phase 1 subphases complete:
+  - Update relevant documentation
+  - Commit documentation changes
+
+# Important Rules
+- **MUST use git worktree** (named after issue)
+- Stay in worktree directory only
+- **NO merge to main branch**
+- **NO git push operations**
+- Only work on Phase 1
+- Stop after each subphase completion
+- Only lint/typecheck NEW code
+- Commit after each successful subphase
+- **PUNISHMENT for violating worktree rules**
+```
+
+### Example Usage
+
+```bash
+/phase-planner "Add user authentication with JWT tokens" "issue-auth-jwt"
+
+# Claude Code will:
+# 1. Create worktree:
+!git worktree add ./issue-auth-jwt -b issue-auth-jwt
+!cd issue-auth-jwt
+
+# 2. Implement Phase 1:
+Phase 1: Core Authentication Setup
+├── 1.1: Create auth middleware
+│   ├── Implement middleware
+│   ├── !npm run lint src/middleware/auth.js
+│   ├── !npm run typecheck src/middleware/auth.js
+│   ├── !npm run build
+│   └── !git commit -m "feat(phase-1.1): add auth middleware"
+├── 1.2: Add JWT token generation
+│   ├── Implement token service
+│   ├── !npm run lint src/services/token.js
+│   ├── !npm run typecheck src/services/token.js
+│   ├── !npm run build
+│   └── !git commit -m "feat(phase-1.2): add JWT token generation"
+└── 1.3: Create login endpoint
+    ├── Implement endpoint
+    ├── !npm run lint src/routes/auth.js
+    ├── !npm run typecheck src/routes/auth.js
+    ├── !npm run build
+    └── !git commit -m "feat(phase-1.3): create login endpoint"
+```
+
+### Validation Checklist
+- [ ] **Git worktree created with issue name**
+- [ ] **All work done in worktree directory**
+- [ ] Each subphase has clear deliverable
+- [ ] Lint/typecheck only new code
+- [ ] Build passes before commit
+- [ ] Commit message follows convention
+- [ ] Documentation updated at phase end
+- [ ] **NO merge to main branch**
+- [ ] **NO push operations**
+- [ ] No operations outside worktree
+
+### Key Benefits
+1. **Isolated Development**: Git worktree keeps work separate from main
+2. **Incremental Progress**: Each subphase is independently committed
+3. **Quality Assurance**: Automated checks before each commit
+4. **Clean History**: Structured commit messages
+5. **Focused Scope**: Only Phase 1 implementation
+6. **Safe Operation**: No merge/push, stays in worktree
+7. **Issue Tracking**: Worktree name matches issue for clarity

{tunacode_cli-0.0.69 → tunacode_cli-0.0.71}/.claude/settings.local.json

@@ -121,7 +121,9 @@
       "Bash(hatch env:*)",
       "Bash(hatch run pip:*)",
       "Bash(./scripts/install_linux.sh:*)",
-      "Bash(hatch run pre-commit run:*)"
+      "Bash(hatch run pre-commit run:*)",
+      "Bash(./scripts/setup_dev_env.sh:*)",
+      "Bash(hatch run tunacode:*)"
     ]
   },
   "enableAllProjectMcpServers": true,

{tunacode_cli-0.0.69 → tunacode_cli-0.0.71}/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.69] - 2025-08-21
+
+### Summary
+This release includes comprehensive command system documentation, updated model configurations, and builds upon recent community contributions including the slash command system by @Lftobs (#85) and onboarding improvements by @ryumacodes (#88).
+
+### Changed
+- Updated OpenRouter GPT model reference from `gpt-4o` to `gpt-4.1` in setup configuration
+
+### Added
+- Additional development documentation in `.claude/` directory
+  - Model updates documentation
+  - Slash commands documentation
+  - Onboarding improvements documentation
+
+## [0.0.68] - 2025-08-21
+
+### Added
+- **Comprehensive Command System Documentation**
+  - Created `command-system-architecture.md` with technical overview of command infrastructure
+  - Created `creating-custom-commands.md` with step-by-step guide for developers
+  - Updated user documentation with slash command information
+  - Added `/command-reload` command documentation
+
+### Fixed
+- Removed broken link to non-existent `templates.md` file in documentation
+
 ## [Unreleased] - 2025-08-20
 
 ### Added

{tunacode_cli-0.0.69 → tunacode_cli-0.0.71}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tunacode-cli
-Version: 0.0.69
+Version: 0.0.71
 Summary: Your agentic CLI developer.
 Project-URL: Homepage, https://tunacode.xyz/
 Project-URL: Repository, https://github.com/alchemiststudiosDOTai/tunacode
@@ -100,7 +100,7 @@ See the [Hatch Build System Guide](documentation/development/hatch-build-system.
 
 ## Configuration
 
-Choose your AI provider and set your API key. For more details, see the [Configuration Section](documentation/user/getting-started.md#2-configuration) in the Getting Started Guide.
+Choose your AI provider and set your API key. For more details, see the [Configuration Section](documentation/user/getting-started.md#2-configuration) in the Getting Started Guide. For local models (LM Studio, Ollama, etc.), see the [Local Models Setup Guide](documentation/configuration/local-models.md).
 
 ### Recommended Models
 

{tunacode_cli-0.0.69 → tunacode_cli-0.0.71}/README.md

@@ -52,7 +52,7 @@ See the [Hatch Build System Guide](documentation/development/hatch-build-system.
 
 ## Configuration
 
-Choose your AI provider and set your API key. For more details, see the [Configuration Section](documentation/user/getting-started.md#2-configuration) in the Getting Started Guide.
+Choose your AI provider and set your API key. For more details, see the [Configuration Section](documentation/user/getting-started.md#2-configuration) in the Getting Started Guide. For local models (LM Studio, Ollama, etc.), see the [Local Models Setup Guide](documentation/configuration/local-models.md).
 
 ### Recommended Models
 

{tunacode_cli-0.0.69 → tunacode_cli-0.0.71}/documentation/README.md

@@ -12,6 +12,7 @@ documentation/
 │   └── main-agent-architecture.md
 ├── configuration/         # System configuration docs
 │   ├── config-file-example.md
+│   ├── local-models.md
 │   └── logging-configuration.md
 ├── development/          # Development practices
 │   ├── codebase-hygiene.md
@@ -36,4 +37,5 @@ General project documentation for features, architecture, and best practices.
 - [Creating Custom Commands](development/creating-custom-commands.md) - Step-by-step guide for creating built-in and slash commands.
 - [Hatch Build System](development/hatch-build-system.md) - Complete guide to using Hatch for development and building.
 - [Configuration File Example](configuration/config-file-example.md) - Complete example of `~/.config/tunacode.json` with all available settings.
+- [Local Models Setup](configuration/local-models.md) - Guide for using local models with LM Studio or any OpenAI-compatible API.
 - [Performance Optimizations](development/performance-optimizations.md) - Major performance improvements and optimization strategies.

tunacode_cli-0.0.71/documentation/configuration/local-models.md

@@ -0,0 +1,107 @@
+# Using Local Models with TunaCode
+
+TunaCode supports any OpenAI-compatible API, including locally hosted models via LM Studio, Ollama, or other local LLM servers.
+
+## Quick Setup for LM Studio
+
+LM Studio provides an OpenAI-compatible API server for running models locally. Configure TunaCode to use it with this configuration:
+
+```json
+{
+  "default_model": "openai:model-name-here",
+  "env": {
+    "OPENAI_API_KEY": "sk-dummy",
+    "OPENAI_BASE_URL": "http://localhost:1234/v1"
+  }
+}
+```
+
+## Complete Working Example
+
+Here's a full configuration file (`~/.config/tunacode.json`) for local models:
+
+```json
+{
+  "default_model": "openai:qwen/qwen3-4b-2507",
+  "env": {
+    "ANTHROPIC_API_KEY": "",
+    "GEMINI_API_KEY": "",
+    "OPENAI_API_KEY": "sk-dummy",
+    "OPENROUTER_API_KEY": "",
+    "OPENAI_BASE_URL": "http://localhost:1234/v1"
+  },
+  "settings": {
+    "max_retries": 10,
+    "max_iterations": 40,
+    "context_window_size": 200000
+  }
+}
+```
+
+## Key Configuration Points
+
+### Base URL Format
+- **Correct**: `http://localhost:1234/v1`
+- **Wrong**: `http://localhost:1234/v1/chat/completions`
+
+The base URL must end at `/v1`. TunaCode automatically appends the appropriate endpoint paths.
+
+### Model Name
+Use the `openai:` prefix followed by your model name:
+- LM Studio: `openai:model-name` (check LM Studio for exact name)
+- Ollama: `openai:llama2`, `openai:mistral`, etc.
+- Custom: `openai:your-model-id`
+
+### API Key Requirement
+Even though local models don't require authentication, the OpenAI client library requires a non-empty API key. Use `"sk-dummy"` or any placeholder value.
+
+## Setup Methods
+
+### Method 1: Direct Configuration
+Edit `~/.config/tunacode.json` with the configuration above.
+
+### Method 2: CLI Flags
+```bash
+tunacode --model "openai:your-model" \
+         --baseurl "http://localhost:1234/v1" \
+         --key "sk-dummy"
+```
+
+### Method 3: Environment Variables
+```bash
+export OPENAI_BASE_URL="http://localhost:1234/v1"
+export OPENAI_API_KEY="sk-dummy"
+tunacode --model "openai:your-model"
+```
+
+## Compatibility
+
+This configuration works with any OpenAI-compatible API server:
+- **LM Studio**: Default port 1234
+- **Ollama**: Usually port 11434 (`http://localhost:11434/v1`)
+- **LocalAI**: Default port 8080
+- **Text Generation WebUI**: With OpenAI extension
+- **vLLM**: OpenAI-compatible server mode
+- **Any custom OpenAI-compatible implementation**
+
+## Troubleshooting
+
+### Connection Refused
+- Ensure your local server is running
+- Check the port number matches your server configuration
+- Try `curl http://localhost:1234/v1/models` to test connectivity
+
+### Bad Request Errors
+- Verify the model name matches what your server expects
+- Check the base URL format (must end with `/v1`)
+- Ensure the server implements OpenAI's chat completions endpoint
+
+### Model Not Found
+- List available models: `curl http://localhost:1234/v1/models`
+- Update `default_model` to match an available model
+
+## Performance Tips
+
+- Set `context_window_size` to match your model's capabilities
+- Adjust `max_iterations` based on your local compute resources
+- Consider reducing `max_retries` for faster failure detection with local models

tunacode_cli-0.0.71/planner.md

@@ -0,0 +1,29 @@
+Tutorial skipped. Use /quickstart anytime to start it!
+ERROR:ui:Set the `OPENROUTER_API_KEY` environment variable or pass it via `OpenRouterProvider(api_key=...)`to use the OpenRouter provider.
+
+Traceback:
+Traceback (most recent call last):
+  File "/root/.tunacode-venv/lib/python3.12/site-packages/tunacode/cli/main.py", line 72, in async_main
+    await repl(state_manager)
+  File "/root/.tunacode-venv/lib/python3.12/site-packages/tunacode/cli/repl.py", line 452, in repl
+    instance = agent.get_or_create_agent(state_manager.session.current_model, state_manager)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/root/.tunacode-venv/lib/python3.12/site-packages/tunacode/core/agents/agent_components/agent_config.py", line 281, in get_or_create_agent
+    agent = Agent(
+            ^^^^^^
+  File "/root/.tunacode-venv/lib/python3.12/site-packages/pydantic_ai/agent.py", line 282, in __init__
+    self.model = models.infer_model(model)
+                 ^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/root/.tunacode-venv/lib/python3.12/site-packages/pydantic_ai/models/__init__.py", line 497, in infer_model
+    return OpenAIModel(model_name, provider=provider)
+           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/root/.tunacode-venv/lib/python3.12/site-packages/pydantic_ai/models/openai.py", line 188, in __init__
+    provider = infer_provider(provider)
+               ^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/root/.tunacode-venv/lib/python3.12/site-packages/pydantic_ai/providers/__init__.py", line 58, in infer_provider
+    return OpenRouterProvider()
+           ^^^^^^^^^^^^^^^^^^^^
+  File "/root/.tunacode-venv/lib/python3.12/site-packages/pydantic_ai/providers/openrouter.py", line 58, in __init__
+    raise UserError(
+pydantic_ai.exceptions.UserError: Set the `OPENROUTER_API_KEY` environment variable or pass it
+via `OpenRouterProvider(api_key=...)`to use the OpenRouter provider.

{tunacode_cli-0.0.69 → tunacode_cli-0.0.71}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "tunacode-cli"
 
-version = "0.0.69"
+version = "0.0.71"
 description = "Your agentic CLI developer."
 keywords = ["cli", "agent", "development", "automation"]
 readme = "README.md"
@@ -170,7 +170,7 @@ typecheck = "mypy src/"
 security = "bandit -r src/ -ll"
 
 # Version management
-version = "0.0.69"
+version = "0.0.71"
 
 # Release workflow
 release = [

{tunacode_cli-0.0.69 → tunacode_cli-0.0.71}/src/tunacode/cli/main.py

@@ -77,7 +77,8 @@ def main(
             from tunacode.exceptions import ConfigurationError
 
             if isinstance(e, ConfigurationError):
-                # ConfigurationError already printed helpful message, just exit cleanly
+                # Display the configuration error message
+                await ui.error(str(e))
                 update_task.cancel()  # Cancel the update check
                 return
             import traceback

{tunacode_cli-0.0.69 → tunacode_cli-0.0.71}/src/tunacode/constants.py

@@ -9,7 +9,7 @@ from enum import Enum
 
 # Application info
 APP_NAME = "TunaCode"
-APP_VERSION = "0.0.69"
+APP_VERSION = "0.0.71"
 
 
 # File patterns

{tunacode_cli-0.0.69 → tunacode_cli-0.0.71}/src/tunacode/core/setup/config_setup.py

@@ -16,6 +16,7 @@ from tunacode.exceptions import ConfigurationError
 from tunacode.types import ConfigFile, ConfigPath, UserConfig
 from tunacode.ui import console as ui
 from tunacode.utils import system, user_configuration
+from tunacode.utils.api_key_validation import validate_api_key_for_model
 from tunacode.utils.text_utils import key_to_title
 
 
@@ -44,6 +45,10 @@ class ConfigSetup(BaseSetup):
         self.state_manager.session.device_id = system.get_device_id()
         loaded_config = user_configuration.load_config()
 
+        # Set the loaded config to session BEFORE initializing first-time user
+        if loaded_config:
+            self.state_manager.session.user_config = loaded_config
+
         # Initialize first-time user settings if needed
         user_configuration.initialize_first_time_user(self.state_manager)
 
@@ -134,11 +139,15 @@ class ConfigSetup(BaseSetup):
                 )
             )
 
-        # No model validation - trust user's model choice
+        # Validate API key exists for the selected model
+        model = self.state_manager.session.user_config["default_model"]
+        is_valid, error_msg = validate_api_key_for_model(
+            model, self.state_manager.session.user_config
+        )
+        if not is_valid:
+            raise ConfigurationError(error_msg)
 
-        self.state_manager.session.current_model = self.state_manager.session.user_config[
-            "default_model"
-        ]
+        self.state_manager.session.current_model = model
 
     async def validate(self) -> bool:
         """Validate that configuration is properly set up."""
@@ -148,6 +157,17 @@ class ConfigSetup(BaseSetup):
             valid = False
         elif not self.state_manager.session.user_config.get("default_model"):
             valid = False
+        else:
+            # Validate API key exists for the selected model
+            model = self.state_manager.session.user_config.get("default_model")
+            is_valid, error_msg = validate_api_key_for_model(
+                model, self.state_manager.session.user_config
+            )
+            if not is_valid:
+                valid = False
+                # Store error message for later use
+                setattr(self.state_manager, "_config_error", error_msg)
+
         # Cache result for fastpath
         if valid:
             setattr(self.state_manager, "_config_valid", True)

tunacode_cli-0.0.71/src/tunacode/utils/api_key_validation.py

@@ -0,0 +1,93 @@
+"""
+Module: tunacode.utils.api_key_validation
+
+Utilities for validating API keys are configured for the selected model.
+"""
+
+from typing import Optional, Tuple
+
+from tunacode.types import UserConfig
+
+
+def get_required_api_key_for_model(model: str) -> Tuple[Optional[str], str]:
+    """
+    Determine which API key is required for a given model.
+
+    Args:
+        model: Model identifier in format "provider:model-name"
+
+    Returns:
+        Tuple of (api_key_name, provider_name) or (None, "unknown") if no specific key required
+    """
+    if not model or ":" not in model:
+        return None, "unknown"
+
+    provider = model.split(":")[0].lower()
+
+    # Map providers to their required API keys
+    provider_key_map = {
+        "openrouter": ("OPENROUTER_API_KEY", "OpenRouter"),
+        "openai": ("OPENAI_API_KEY", "OpenAI"),
+        "anthropic": ("ANTHROPIC_API_KEY", "Anthropic"),
+        "google": ("GEMINI_API_KEY", "Google"),
+        "google-gla": ("GEMINI_API_KEY", "Google"),
+        "gemini": ("GEMINI_API_KEY", "Google"),
+    }
+
+    return provider_key_map.get(provider, (None, provider))
+
+
+def validate_api_key_for_model(model: str, user_config: UserConfig) -> Tuple[bool, Optional[str]]:
+    """
+    Check if the required API key exists for the given model.
+
+    Args:
+        model: Model identifier in format "provider:model-name"
+        user_config: User configuration containing env variables
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    api_key_name, provider_name = get_required_api_key_for_model(model)
+
+    if not api_key_name:
+        # No specific API key required (might be custom endpoint)
+        return True, None
+
+    env_config = user_config.get("env", {})
+    api_key = env_config.get(api_key_name, "").strip()
+
+    if not api_key:
+        return False, (
+            f"No API key found for {provider_name}.\n"
+            f"Please run 'tunacode --setup' to configure your API key."
+        )
+
+    return True, None
+
+
+def get_configured_providers(user_config: UserConfig) -> list[str]:
+    """
+    Get list of providers that have API keys configured.
+
+    Args:
+        user_config: User configuration containing env variables
+
+    Returns:
+        List of provider names that have API keys set
+    """
+    env_config = user_config.get("env", {})
+    configured = []
+
+    provider_map = {
+        "OPENROUTER_API_KEY": "openrouter",
+        "OPENAI_API_KEY": "openai",
+        "ANTHROPIC_API_KEY": "anthropic",
+        "GEMINI_API_KEY": "google",
+    }
+
+    for key_name, provider in provider_map.items():
+        if env_config.get(key_name, "").strip():
+            configured.append(provider)
+
+    return configured