klaude-code 1.2.6__py3-none-any.whl

klaude_code/command/prompt-init.md

@@ -0,0 +1,45 @@
+---
+description: Create an AGENTS.md file with instructions for agent
+from: https://github.com/openai/codex/blob/main/codex-rs/tui/prompt_for_init_command.md
+---
+
+Generate/Update a file named AGENTS.md that serves as a contributor guide for this repository.
+Your goal is to produce a clear, concise, and well-structured document with descriptive headings and actionable explanations for each section.
+Follow the outline below, but adapt as needed — add sections if relevant, and omit those that do not apply to this project.
+
+Document Requirements
+
+- Title the document "Repository Guidelines".
+- Use Markdown headings (#, ##, etc.) for structure.
+- Keep the document concise. 200-400 words is optimal.
+- Keep explanations short, direct, and specific to this repository.
+- Provide examples where helpful (commands, directory paths, naming patterns).
+- Maintain a professional, instructional tone.
+
+Recommended Sections
+
+Project Structure & Module Organization
+
+- Outline the project structure, including where the source code, tests, and assets are located.
+
+Build, Test, and Development Commands
+
+- List key commands for building, testing, and running locally (e.g., npm test, make build).
+- Briefly explain what each command does.
+
+Coding Style & Naming Conventions
+
+- Specify indentation rules, language-specific style preferences, and naming patterns.
+- Include any formatting or linting tools used.
+
+Testing Guidelines
+
+- Identify testing frameworks and coverage requirements.
+- State test naming conventions and how to run tests.
+
+Commit & Pull Request Guidelines
+
+- Summarize commit message conventions found in the project’s Git history.
+- Outline pull request requirements (descriptions, linked issues, screenshots, etc.).
+
+(Optional) Add other sections if relevant, such as Security & Configuration Tips, Architecture Overview, or Agent-Specific Instructions.

klaude_code/command/prompt_command.py

@@ -0,0 +1,69 @@
+from importlib.resources import files
+
+import yaml
+
+from klaude_code.command.command_abc import CommandABC, CommandResult, InputAction
+from klaude_code.core.agent import Agent
+from klaude_code.protocol import commands
+
+
+class PromptCommand(CommandABC):
+    """Command that loads a prompt from a markdown file."""
+
+    def __init__(self, filename: str, command_name: str | None = None):
+        self._filename = filename
+        self._command_name = command_name or filename.replace("prompt_", "").replace("prompt-", "").replace(".md", "")
+        self._content: str | None = None
+        self._metadata: dict[str, str] = {}
+
+    @property
+    def name(self) -> str | commands.CommandName:
+        return self._command_name
+
+    @property
+    def template_name(self) -> str:
+        """filename of the markdown prompt template in the command package."""
+        return self._filename
+
+    def _ensure_loaded(self):
+        if self._content is not None:
+            return
+
+        try:
+            raw_text = files("klaude_code.command").joinpath(self.template_name).read_text(encoding="utf-8")
+
+            if raw_text.startswith("---"):
+                parts = raw_text.split("---", 2)
+                if len(parts) >= 3:
+                    self._metadata = yaml.safe_load(parts[1]) or {}
+                    self._content = parts[2].strip()
+                    return
+
+            self._metadata = {}
+            self._content = raw_text
+        except Exception:
+            self._metadata = {"description": "Error loading template"}
+            self._content = f"Error loading template: {self.template_name}"
+
+    @property
+    def summary(self) -> str:
+        self._ensure_loaded()
+        return self._metadata.get("description", f"Execute {self.name} command")
+
+    @property
+    def support_addition_params(self) -> bool:
+        return True
+
+    async def run(self, raw: str, agent: Agent) -> CommandResult:
+        self._ensure_loaded()
+        template_content = self._content or ""
+        user_input = raw.strip() or "<none>"
+
+        if "$ARGUMENTS" in template_content:
+            final_prompt = template_content.replace("$ARGUMENTS", user_input)
+        else:
+            final_prompt = template_content
+            if user_input:
+                final_prompt += f"\n\nAdditional Instructions:\n{user_input}"
+
+        return CommandResult(actions=[InputAction.run_agent(final_prompt)])

klaude_code/command/refresh_cmd.py

@@ -0,0 +1,43 @@
+from klaude_code.command.command_abc import CommandABC, CommandResult
+from klaude_code.command.registry import register_command
+from klaude_code.core.agent import Agent
+from klaude_code.protocol import commands, events
+
+
+@register_command
+class RefreshTerminalCommand(CommandABC):
+    """Refresh terminal display"""
+
+    @property
+    def name(self) -> commands.CommandName:
+        return commands.CommandName.REFRESH_TERMINAL
+
+    @property
+    def summary(self) -> str:
+        return "Refresh terminal display"
+
+    @property
+    def is_interactive(self) -> bool:
+        return True
+
+    async def run(self, raw: str, agent: Agent) -> CommandResult:
+        import os
+
+        os.system("cls" if os.name == "nt" else "clear")
+
+        result = CommandResult(
+            events=[
+                events.WelcomeEvent(
+                    work_dir=str(agent.session.work_dir),
+                    llm_config=agent.get_llm_client().get_llm_config(),
+                ),
+                events.ReplayHistoryEvent(
+                    session_id=agent.session.id,
+                    events=list(agent.session.get_history_item()),
+                    updated_at=agent.session.updated_at,
+                    is_load=False,
+                ),
+            ]
+        )
+
+        return result

klaude_code/command/registry.py

@@ -0,0 +1,110 @@
+from importlib.resources import files
+from typing import TYPE_CHECKING, TypeVar
+
+from klaude_code.command.command_abc import CommandResult, InputAction
+from klaude_code.command.prompt_command import PromptCommand
+from klaude_code.core.agent import Agent
+from klaude_code.protocol import commands, events, model
+
+if TYPE_CHECKING:
+    from .command_abc import CommandABC
+
+_COMMANDS: dict[commands.CommandName | str, "CommandABC"] = {}
+
+T = TypeVar("T", bound="CommandABC")
+
+
+def register_command(cls: type[T]) -> type[T]:
+    """Decorator to register a command class in the global registry."""
+    instance = cls()
+    _COMMANDS[instance.name] = instance
+    return cls
+
+
+def load_prompt_commands():
+    """Dynamically load prompt-based commands from the command directory."""
+    try:
+        command_files = files("klaude_code.command").iterdir()
+        for file_path in command_files:
+            name = file_path.name
+            if (name.startswith("prompt_") or name.startswith("prompt-")) and name.endswith(".md"):
+                cmd = PromptCommand(name)
+                _COMMANDS[cmd.name] = cmd
+    except Exception:
+        # If resource loading fails, just ignore
+        pass
+
+
+def get_commands() -> dict[commands.CommandName | str, "CommandABC"]:
+    """Get all registered commands."""
+    return _COMMANDS.copy()
+
+
+def is_slash_command_name(name: str) -> bool:
+    return name in _COMMANDS
+
+
+async def dispatch_command(raw: str, agent: Agent) -> CommandResult:
+    # Detect command name
+    if not raw.startswith("/"):
+        return CommandResult(actions=[InputAction.run_agent(raw)])
+
+    splits = raw.split(" ", maxsplit=1)
+    command_name_raw = splits[0][1:]
+    rest = " ".join(splits[1:]) if len(splits) > 1 else ""
+
+    # Try to match against registered commands (both Enum and string keys)
+    command_key = None
+
+    # First try exact string match
+    if command_name_raw in _COMMANDS:
+        command_key = command_name_raw
+    else:
+        # Then try Enum conversion for standard commands
+        try:
+            enum_key = commands.CommandName(command_name_raw)
+            if enum_key in _COMMANDS:
+                command_key = enum_key
+        except ValueError:
+            pass
+
+    if command_key is None:
+        return CommandResult(actions=[InputAction.run_agent(raw)])
+
+    command = _COMMANDS[command_key]
+    command_identifier: commands.CommandName | str = command.name
+
+    try:
+        return await command.run(rest, agent)
+    except Exception as e:
+        command_output = (
+            model.CommandOutput(command_name=command_identifier, is_error=True)
+            if isinstance(command_identifier, commands.CommandName)
+            else None
+        )
+        return CommandResult(
+            events=[
+                events.DeveloperMessageEvent(
+                    session_id=agent.session.id,
+                    item=model.DeveloperMessageItem(
+                        content=f"Command {command_identifier} error: [{e.__class__.__name__}] {str(e)}",
+                        command_output=command_output,
+                    ),
+                )
+            ]
+        )
+
+
+def has_interactive_command(raw: str) -> bool:
+    if not raw.startswith("/"):
+        return False
+    splits = raw.split(" ", maxsplit=1)
+    command_name_raw = splits[0][1:]
+    try:
+        command_name = commands.CommandName(command_name_raw)
+    except ValueError:
+        return False
+    if command_name not in _COMMANDS:
+        return False
+    command = _COMMANDS[command_name]
+    return command.is_interactive

klaude_code/command/status_cmd.py

@@ -0,0 +1,111 @@
+from klaude_code.command.command_abc import CommandABC, CommandResult
+from klaude_code.command.registry import register_command
+from klaude_code.core.agent import Agent
+from klaude_code.protocol import commands, events, model
+from klaude_code.session.session import Session
+
+
+def accumulate_session_usage(session: Session) -> tuple[model.Usage, int]:
+    """Accumulate usage statistics from all ResponseMetadataItems in session history.
+
+    Returns:
+        A tuple of (accumulated_usage, task_count)
+    """
+    total = model.Usage()
+    task_count = 0
+
+    for item in session.conversation_history:
+        if isinstance(item, model.ResponseMetadataItem) and item.usage:
+            task_count += 1
+            usage = item.usage
+            total.input_tokens += usage.input_tokens
+            total.cached_tokens += usage.cached_tokens
+            total.reasoning_tokens += usage.reasoning_tokens
+            total.output_tokens += usage.output_tokens
+            total.total_tokens += usage.total_tokens
+
+            # Accumulate costs
+            if usage.input_cost is not None:
+                total.input_cost = (total.input_cost or 0.0) + usage.input_cost
+            if usage.output_cost is not None:
+                total.output_cost = (total.output_cost or 0.0) + usage.output_cost
+            if usage.cache_read_cost is not None:
+                total.cache_read_cost = (total.cache_read_cost or 0.0) + usage.cache_read_cost
+            if usage.total_cost is not None:
+                total.total_cost = (total.total_cost or 0.0) + usage.total_cost
+
+            # Keep the latest context_usage_percent
+            if usage.context_usage_percent is not None:
+                total.context_usage_percent = usage.context_usage_percent
+
+    return total, task_count
+
+
+def _format_tokens(tokens: int) -> str:
+    """Format token count with K/M suffix for readability."""
+    if tokens >= 1_000_000:
+        return f"{tokens / 1_000_000:.2f}M"
+    if tokens >= 1_000:
+        return f"{tokens / 1_000:.1f}K"
+    return str(tokens)
+
+
+def _format_cost(cost: float | None) -> str:
+    """Format cost in USD."""
+    if cost is None:
+        return "-"
+    if cost < 0.01:
+        return f"${cost:.4f}"
+    return f"${cost:.2f}"
+
+
+def format_status_content(usage: model.Usage) -> str:
+    """Format session status as comma-separated text."""
+    parts: list[str] = []
+
+    parts.append(f"Input: {_format_tokens(usage.input_tokens)}")
+    if usage.cached_tokens > 0:
+        parts.append(f"Cached: {_format_tokens(usage.cached_tokens)}")
+    parts.append(f"Output: {_format_tokens(usage.output_tokens)}")
+    parts.append(f"Total: {_format_tokens(usage.total_tokens)}")
+
+    if usage.total_cost is not None:
+        parts.append(f"Cost: {_format_cost(usage.total_cost)}")
+
+    return ", ".join(parts)
+
+
+@register_command
+class StatusCommand(CommandABC):
+    """Display session usage statistics."""
+
+    @property
+    def name(self) -> commands.CommandName:
+        return commands.CommandName.STATUS
+
+    @property
+    def summary(self) -> str:
+        return "Show session usage statistics"
+
+    async def run(self, raw: str, agent: Agent) -> CommandResult:
+        session = agent.session
+        usage, task_count = accumulate_session_usage(session)
+
+        event = events.DeveloperMessageEvent(
+            session_id=session.id,
+            item=model.DeveloperMessageItem(
+                content=format_status_content(usage),
+                command_output=model.CommandOutput(
+                    command_name=self.name,
+                    ui_extra=model.ToolResultUIExtra(
+                        type=model.ToolResultUIExtraType.SESSION_STATUS,
+                        session_status=model.SessionStatusUIExtra(
+                            usage=usage,
+                            task_count=task_count,
+                        ),
+                    ),
+                ),
+            ),
+        )
+
+        return CommandResult(events=[event])

klaude_code/command/terminal_setup_cmd.py

@@ -0,0 +1,252 @@
+import os
+import subprocess
+from pathlib import Path
+
+from klaude_code.command.command_abc import CommandABC, CommandResult
+from klaude_code.command.registry import register_command
+from klaude_code.core.agent import Agent
+from klaude_code.protocol import commands, events, model
+
+
+@register_command
+class TerminalSetupCommand(CommandABC):
+    """Setup shift+enter newline functionality in terminal"""
+
+    @property
+    def name(self) -> commands.CommandName:
+        return commands.CommandName.TERMINAL_SETUP
+
+    @property
+    def summary(self) -> str:
+        return "Install shift+enter key binding for newlines"
+
+    @property
+    def is_interactive(self) -> bool:
+        return False
+
+    async def run(self, raw: str, agent: Agent) -> CommandResult:
+        term_program = os.environ.get("TERM_PROGRAM", "").lower()
+
+        try:
+            if term_program == "ghostty":
+                message = self._setup_ghostty()
+            elif term_program == "iterm.app":
+                message = self._setup_iterm()
+            elif term_program == "vscode":
+                # VS Code family terminals (VS Code, Windsurf, Cursor) all report TERM_PROGRAM=vscode
+                message = self._setup_vscode_family()
+            else:
+                # Provide generic manual configuration guide for unknown or unsupported terminals
+                message = self._setup_generic(term_program)
+
+            return self._create_success_result(agent, message)
+
+        except Exception as e:
+            return self._create_error_result(agent, f"Error configuring terminal: {str(e)}")
+
+    def _setup_ghostty(self) -> str:
+        """Configure shift+enter newline for Ghostty terminal"""
+        config_dir = Path.home() / ".config" / "ghostty"
+        config_file = config_dir / "config"
+
+        keybind_line = 'keybind="shift+enter=text:\\n"'
+
+        # Ensure config directory exists
+        config_dir.mkdir(parents=True, exist_ok=True)
+
+        # Check if configuration already exists in config file
+        if config_file.exists():
+            content = config_file.read_text()
+            if keybind_line in content or 'keybind="shift+enter=' in content:
+                return "Ghostty terminal shift+enter newline configuration already exists"
+
+        # Add configuration
+        with config_file.open("a", encoding="utf-8") as f:
+            if config_file.exists() and not config_file.read_text().endswith("\n"):
+                f.write("\n")
+            f.write(f"{keybind_line}\n")
+
+        return f"Added shift+enter newline configuration for Ghostty terminal to {config_file}"
+
+    def _setup_iterm(self) -> str:
+        """Configure shift+enter newline for iTerm terminal using defaults command"""
+        try:
+            # First check if iTerm preferences exist
+            prefs_path = Path.home() / "Library" / "Preferences" / "com.googlecode.iterm2.plist"
+            if not prefs_path.exists():
+                return "iTerm preferences file not found. Please open iTerm first to create initial preferences."
+
+            # Check if the key binding already exists
+            check_cmd = ["defaults", "read", "com.googlecode.iterm2", "New Bookmarks"]
+
+            try:
+                result = subprocess.run(check_cmd, capture_output=True, text=True, check=True)
+                # If we can read bookmarks, iTerm is properly configured
+            except subprocess.CalledProcessError:
+                return "Unable to read iTerm configuration. Please ensure iTerm is properly installed and has been opened at least once."
+
+            # Add to the default profile's keyboard map
+            add_keymap_cmd = [
+                "defaults",
+                "write",
+                "com.googlecode.iterm2",
+                "GlobalKeyMap",
+                "-dict-add",
+                # Do not include quotes when passing args as a list (no shell)
+                "0x0d-0x20000",
+                # Pass Property List dict directly; \n should be literal backslash-n so iTerm parses newline
+                '{Action=12;Text="\\\\n";}',
+            ]
+            # Execute without shell so arguments are passed correctly
+            result = subprocess.run(add_keymap_cmd, capture_output=True, text=True)
+            print(result.stdout, result.stderr)
+            if result.returncode == 0:
+                return "Successfully configured Shift+Enter for newline in iTerm. Please restart iTerm for changes to take effect."
+            else:
+                # Fallback to manual instructions if defaults command fails
+                return (
+                    "Automatic configuration failed. Please manually configure:\n"
+                    "1. Open iTerm -> Preferences (⌘,)\n"
+                    "2. Go to Profiles -> Keys -> Key Mappings\n"
+                    "3. Click '+' to add: Shift+Enter -> Send Text -> \\n"
+                )
+
+        except Exception as e:
+            raise Exception(f"Error configuring iTerm: {str(e)}")
+
+    def _setup_vscode_family(self) -> str:
+        """Configure shift+enter newline for VS Code family terminals (VS Code, Windsurf, Cursor).
+
+        These editors share TERM_PROGRAM=vscode and use keybindings.json under their respective
+        Application Support folders. We ensure the required keybinding exists; if not, we append it.
+        """
+        base_dir = Path.home() / "Library" / "Application Support"
+        targets = [
+            ("VS Code", base_dir / "Code" / "User" / "keybindings.json"),
+            ("Windsurf", base_dir / "Windsurf" / "User" / "keybindings.json"),
+            ("Cursor", base_dir / "Cursor" / "User" / "keybindings.json"),
+        ]
+
+        mapping_block = r"""    {
+        "key": "shift+enter",
+        "command": "workbench.action.terminal.sendSequence",
+        "args": {
+            "text": "\\\r\n"
+        },
+        "when": "terminalFocus"
+    }"""
+
+        results: list[str] = []
+
+        for name, file_path in targets:
+            try:
+                _, msg = self._ensure_vscode_keybinding(file_path, mapping_block)
+                results.append(f"{name}: {msg}")
+            except Exception as e:  # pragma: no cover - protect against any unexpected FS issue
+                results.append(f"{name}: failed to update keybindings ({e})")
+
+        return "\n".join(results)
+
+    def _ensure_vscode_keybinding(self, path: Path, mapping_block: str) -> tuple[bool, str]:
+        """Ensure the VS Code-style keybinding exists in the given keybindings.json file.
+
+        Returns (added, message).
+        - added=True if we created or modified the file to include the mapping
+        - added=False if mapping already present or file couldn't be safely modified
+        """
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        # If file does not exist, create with the mapping in an array
+        if not path.exists():
+            content = "[\n  " + mapping_block + "\n]\n"
+            path.write_text(content, encoding="utf-8")
+            return True, f"created {path} with Shift+Enter mapping"
+
+        # Read existing content
+        raw = path.read_text(encoding="utf-8")
+        text = raw
+
+        # Quick detection: if both key and command exist together anywhere, assume configured
+        if '"key": "shift+enter"' in text and "workbench.action.terminal.sendSequence" in text:
+            return False, "already configured"
+
+        stripped = text.strip()
+        # If file is empty, write a fresh array
+        if stripped == "":
+            content = "[\n  " + mapping_block + "\n]\n"
+            path.write_text(content, encoding="utf-8")
+            return True, "initialized empty keybindings.json with mapping"
+
+        # If the content contains a top-level array (allowing header comments), append before the final ]
+        open_idx = text.find("[")
+        close_idx = text.rfind("]")
+        if open_idx != -1 and close_idx != -1 and open_idx < close_idx:
+            before = text[:close_idx].rstrip()
+            after = text[close_idx:]
+
+            # Heuristic: treat as non-empty if there's an object marker between [ and ]
+            inner = text[open_idx + 1 : close_idx]
+            has_item = "{" in inner
+
+            # Construct new content by adding optional comma, newline, then our block
+            new_content = before + ("," if has_item else "") + "\n" + mapping_block + "\n" + after
+
+            path.write_text(new_content, encoding="utf-8")
+            return True, "appended mapping"
+
+        # Not an array – avoid modifying to prevent corrupting user config
+        return (
+            False,
+            "unsupported keybindings.json format (not an array); please add mapping manually",
+        )
+
+    def _setup_generic(self, term_program: str) -> str:
+        """Provide generic manual configuration guide for unknown or unsupported terminals"""
+        if term_program:
+            intro = f"Terminal type '{term_program}' is not specifically supported, but you can manually configure shift+enter newline functionality."
+        else:
+            intro = "Unable to detect terminal type, but you can manually configure shift+enter newline functionality."
+
+        message = (
+            f"{intro}\n\n"
+            "General steps to configure shift+enter for newline:\n"
+            "1. Open your terminal's preferences/settings\n"
+            "2. Look for 'Key Bindings', 'Key Mappings', or 'Keyboard' section\n"
+            "3. Add a new key binding:\n"
+            "   - Key combination: Shift+Enter\n"
+            "   - Action: Send text or Insert text\n"
+            "   - Text to send: \\n (literal newline character)\n"
+            "4. Save the configuration\n\n"
+            "Note: The exact steps may vary depending on your terminal application. "
+            "Currently supported terminals with automatic configuration: Ghostty, iTerm.app, VS Code family (VS Code, Windsurf, Cursor)"
+        )
+
+        return message
+
+    def _create_success_result(self, agent: Agent, message: str) -> CommandResult:
+        """Create success result"""
+        return CommandResult(
+            events=[
+                events.DeveloperMessageEvent(
+                    session_id=agent.session.id,
+                    item=model.DeveloperMessageItem(
+                        content=message,
+                        command_output=model.CommandOutput(command_name=self.name, is_error=False),
+                    ),
+                )
+            ]
+        )
+
+    def _create_error_result(self, agent: Agent, message: str) -> CommandResult:
+        """Create error result"""
+        return CommandResult(
+            events=[
+                events.DeveloperMessageEvent(
+                    session_id=agent.session.id,
+                    item=model.DeveloperMessageItem(
+                        content=message,
+                        command_output=model.CommandOutput(command_name=self.name, is_error=True),
+                    ),
+                )
+            ]
+        )

klaude_code/config/__init__.py

@@ -0,0 +1,11 @@
+from .config import Config, config_path, load_config
+from .list_model import display_models_and_providers
+from .select_model import select_model_from_config
+
+__all__ = [
+    "Config",
+    "load_config",
+    "config_path",
+    "display_models_and_providers",
+    "select_model_from_config",
+]