kittycode 0.1.0__tar.gz → 0.1.2__tar.gz

{kittycode-0.1.0 → kittycode-0.1.2}/.gitignore

@@ -1,4 +1,6 @@
 __pycache__/
+tests/__pycache__/
+kittycode/__pycache__/
 *.py[cod]
 *$py.class
 *.egg-info/
@@ -16,4 +18,5 @@ dist/
 .pytest_cache/
 findings.md
 progress.md
-task_plan.md
+task_plan.md
+tests/test_prompt.md

kittycode-0.1.2/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: kittycode
+Version: 0.1.2
+Summary: Minimal AI coding agent with a simple tool loop and skill support.
+Project-URL: Homepage, https://github.com/yejiming/KittyCode
+Project-URL: Repository, https://github.com/yejiming/KittyCode
+Author-email: Jimmy Ye <jiming_ye@163.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,cli,coding,llm
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.84.0
+Requires-Dist: openai>=1.0
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# KittyCode
+
+KittyCode is a minimal terminal coding agent focused on a compact, readable implementation. It keeps the core runtime straightforward, with an agent loop, local tools, context compression, a small command-line interface, and support for both OpenAI-compatible and Anthropic APIs.
+
+## Background
+
+KittyCode follows a simple terminal-agent runtime model:
+
+- A user message is sent through the configured model interface.
+- The model can either answer directly or call tools.
+- Tool calls are executed locally and the results are fed back into the conversation.
+- The loop continues until the model returns plain text.
+
+The project is intentionally small. It includes the core agent runtime, a compact CLI, session persistence, context compression, and a default built-in tool set.
+
+## Features
+
+- Minimal agent loop with optional parallel execution for multiple tool calls.
+- LLM adapter that supports both OpenAI-compatible and Anthropic interfaces.
+- Built-in tools for shell commands, file reading, file writing, targeted editing, glob search, regex search, and sub-agents.
+- Startup skill discovery from `~/.kittycode/skills`, with skill metadata injected into the system prompt each round.
+- Interactive REPL and one-shot command mode.
+- ANSI pixel-cat startup banner.
+- `Esc` interrupt support for stopping the current agent run at the next safe checkpoint.
+- Context compression to keep long sessions manageable.
+- Session save and resume support.
+
+## Requirements
+
+- Python 3.10 or newer
+- An API key for either an OpenAI-compatible endpoint or an Anthropic-compatible endpoint
+
+## Installation
+
+Clone the repository and install it in editable mode:
+
+```bash
+cd KittyCode
+python -m pip install -e .
+```
+
+If you also want the development test dependency:
+
+```bash
+python -m pip install -e .[dev]
+```
+
+## Configuration
+
+KittyCode reads startup configuration from `~/.kittycode/config.json`.
+
+Supported fields:
+
+- `interface`: `openai` or `anthropic`
+- `api_key`
+- `model`
+- `base_url`
+- `max_tokens`
+- `temperature`
+- `max_context`
+
+OpenAI-compatible example:
+
+```json
+{
+	"interface": "openai",
+	"api_key": "sk-...",
+	"model": "gpt-4o",
+	"base_url": "https://api.openai.com/v1",
+	"max_tokens": 4096,
+	"temperature": 0,
+	"max_context": 128000
+}
+```
+
+Anthropic example:
+
+```json
+{
+	"interface": "anthropic",
+	"api_key": "sk-ant-...",
+	"model": "claude-3-7-sonnet-latest",
+	"base_url": "https://api.anthropic.com",
+	"max_tokens": 4096,
+	"temperature": 0,
+	"max_context": 128000
+}
+```
+
+The CLI still allows explicit overrides such as `--model`, `--interface`, `--base-url`, and `--api-key`.
+
+## Skills
+
+At startup, KittyCode scans `~/.kittycode/skills` for skill folders. Each skill should live in its own directory and include a `SKILL.md` file at the top level.
+
+Expected layout:
+
+```text
+~/.kittycode/skills/
+	example-skill/
+		SKILL.md
+		other-files...
+```
+
+KittyCode reads the leading `name` and `description` fields from each `SKILL.md`, keeps the resulting skill list in memory, and inserts the list into the system prompt at the start of every round. The prompt includes:
+
+- `name`
+- `description`
+- `path`
+
+This allows the model to see which local skills are available and decide when to read and use them.
+
+Before each round, KittyCode checks whether the skill directory changed and reloads the cached skill metadata when needed, so adding or editing skills does not require restarting the process.
+
+You can also invoke a loaded skill directly from the CLI with `/<skill name>`.
+
+- `/<skill name>` selects that skill for your next non-command message.
+- `/<skill name> <task>` runs the next request immediately with that skill.
+
+## Usage
+
+Run the interactive terminal UI:
+
+```bash
+kittycode
+```
+
+When the CLI is busy, press `Esc` to interrupt the current run. The stop is cooperative: KittyCode cancels at the next safe checkpoint between LLM streaming, tool dispatch, and loop rounds. A blocking external call may still need to return before the run fully stops.
+
+You can also use the module entry point:
+
+```bash
+python -m kittycode
+```
+
+Run a one-shot prompt and exit:
+
+```bash
+kittycode -p "Explain the project structure"
+```
+
+Resume a saved session:
+
+```bash
+kittycode -r session_1234567890
+```
+
+Override model, interface, or endpoint from the command line:
+
+```bash
+kittycode --interface anthropic --model claude-3-7-sonnet-latest
+```
+
+## Interactive Commands
+
+Inside the REPL, KittyCode supports:
+
+- `/help`
+- `/reset`
+- `/skills`
+- `/<skill name>`
+- `/model <name>`
+- `/tokens`
+- `/compact`
+- `/save`
+- `/sessions`
+- `/quit`
+
+The `/skills` command refreshes the local skill cache if the skill directory has changed and then prints the currently loaded skills.
+Slash commands also support prefix matching while typing, so entering `/` shows matching commands and skills through completion suggestions.
+
+## If `kittycode` Is Still Not Found After `pip install -e .`
+
+The project already declares the console entry point in `pyproject.toml`:
+
+```toml
+[project.scripts]
+kittycode = "kittycode.cli:main"
+```
+
+So if `kittycode` is still unavailable, the usual cause is the local Python install location rather than missing packaging metadata.
+
+Check which Python/pip you used:
+
+```bash
+python3 -m pip --version
+python3 -m site --user-base
+```
+
+On macOS, a user install commonly places scripts under:
+
+```bash
+~/Library/Python/3.11/bin
+```
+
+If that directory is not in `PATH`, the editable install may succeed but the shell still will not find `kittycode`.
+
+For `zsh`, add the corresponding bin directory to your shell profile:
+
+```bash
+export PATH="$HOME/Library/Python/3.11/bin:$PATH"
+```
+
+Then reload the shell:
+
+```bash
+source ~/.zshrc
+```
+
+If the install itself fails with a permissions error while writing a `.pth` file under `~/Library/Python/.../site-packages`, fix that environment issue first or install into a virtual environment before retrying.
+
+## Project Layout
+
+- `kittycode/agent.py`: core agent loop
+- `kittycode/llm.py`: streaming LLM wrapper
+- `kittycode/context.py`: context compression
+- `kittycode/cli.py`: interactive and one-shot CLI
+- `kittycode/session.py`: session persistence
+- `kittycode/tools/`: built-in tools
+- `tests/`: focused runtime and tool tests
+
+## Development
+
+Run the test suite:
+
+```bash
+python -m pytest -q
+```
+
+The current test suite covers the exported API, config-file behavior, provider conversion helpers, context compression, session helpers, the default tool registry, and skill discovery/prompt injection.

{kittycode-0.1.0 → kittycode-0.1.2}/README.md

@@ -20,6 +20,8 @@ The project is intentionally small. It includes the core agent runtime, a compac
 - Built-in tools for shell commands, file reading, file writing, targeted editing, glob search, regex search, and sub-agents.
 - Startup skill discovery from `~/.kittycode/skills`, with skill metadata injected into the system prompt each round.
 - Interactive REPL and one-shot command mode.
+- ANSI pixel-cat startup banner.
+- `Esc` interrupt support for stopping the current agent run at the next safe checkpoint.
 - Context compression to keep long sessions manageable.
 - Session save and resume support.
 
@@ -123,6 +125,8 @@ Run the interactive terminal UI:
 kittycode
 ```
 
+When the CLI is busy, press `Esc` to interrupt the current run. The stop is cooperative: KittyCode cancels at the next safe checkpoint between LLM streaming, tool dispatch, and loop rounds. A blocking external call may still need to return before the run fully stops.
+
 You can also use the module entry point:
 
 ```bash
@@ -165,6 +169,46 @@ Inside the REPL, KittyCode supports:
 The `/skills` command refreshes the local skill cache if the skill directory has changed and then prints the currently loaded skills.
 Slash commands also support prefix matching while typing, so entering `/` shows matching commands and skills through completion suggestions.
 
+## If `kittycode` Is Still Not Found After `pip install -e .`
+
+The project already declares the console entry point in `pyproject.toml`:
+
+```toml
+[project.scripts]
+kittycode = "kittycode.cli:main"
+```
+
+So if `kittycode` is still unavailable, the usual cause is the local Python install location rather than missing packaging metadata.
+
+Check which Python/pip you used:
+
+```bash
+python3 -m pip --version
+python3 -m site --user-base
+```
+
+On macOS, a user install commonly places scripts under:
+
+```bash
+~/Library/Python/3.11/bin
+```
+
+If that directory is not in `PATH`, the editable install may succeed but the shell still will not find `kittycode`.
+
+For `zsh`, add the corresponding bin directory to your shell profile:
+
+```bash
+export PATH="$HOME/Library/Python/3.11/bin:$PATH"
+```
+
+Then reload the shell:
+
+```bash
+source ~/.zshrc
+```
+
+If the install itself fails with a permissions error while writing a `.pth` file under `~/Library/Python/.../site-packages`, fix that environment issue first or install into a virtual environment before retrying.
+
 ## Project Layout
 
 - `kittycode/agent.py`: core agent loop
@@ -183,4 +227,4 @@ Run the test suite:
 python -m pytest -q
 ```
 
-The current test suite covers the exported API, config-file behavior, provider conversion helpers, context compression, session helpers, the default tool registry, and skill discovery/prompt injection.
+The current test suite covers the exported API, config-file behavior, provider conversion helpers, context compression, session helpers, the default tool registry, and skill discovery/prompt injection.

{kittycode-0.1.0 → kittycode-0.1.2}/README_CN.md

@@ -20,6 +20,8 @@ KittyCode 的基本工作方式如下：
 - 内置 Bash、读文件、写文件、精确替换编辑、Glob 搜索、Grep 搜索、子代理等工具。
 - 启动时自动扫描 `~/.kittycode/skills`，并在每轮系统 prompt 开头注入可用 skill 列表。
 - 支持交互式 REPL 和单次命令模式。
+- 启动时展示 ANSI 彩色像素猫。
+- 支持在执行过程中按 `Esc` 中断当前任务。
 - 支持长会话上下文压缩。
 - 支持保存和恢复历史会话。
 
@@ -123,6 +125,8 @@ KittyCode 启动时会扫描 `~/.kittycode/skills` 目录。每个 skill 使用
 kittycode
 ```
 
+当 CLI 正在执行时，可以按 `Esc` 中断当前任务。这个中断是协作式的：KittyCode 会在下一处安全检查点停止，例如 LLM 流式输出过程中、工具调度前后或下一轮循环开始前。如果某个底层外部调用本身是阻塞的，仍然可能要等该调用返回后才会完全结束。
+
 也可以直接通过模块启动：
 
 ```bash
@@ -165,6 +169,46 @@ kittycode --interface anthropic --model claude-3-7-sonnet-latest
 `/skills` 命令会在检测到 skill 目录变化时刷新本地缓存，并输出当前已加载的 skill 列表。
 当输入以 `/` 开头时，CLI 还会根据前缀自动补全可用命令和 skill。
 
+## 如果执行 `pip install -e .` 后仍然找不到 `kittycode`
+
+项目本身已经在 `pyproject.toml` 中声明了控制台入口：
+
+```toml
+[project.scripts]
+kittycode = "kittycode.cli:main"
+```
+
+所以如果仍然不能直接执行 `kittycode`，通常不是因为项目没有声明入口，而是 Python 本地安装路径或 shell `PATH` 的问题。
+
+先确认你实际使用的是哪个 Python/pip：
+
+```bash
+python3 -m pip --version
+python3 -m site --user-base
+```
+
+在 macOS 上，用户级安装通常会把脚本放到类似下面的目录：
+
+```bash
+~/Library/Python/3.11/bin
+```
+
+如果这个目录不在 `PATH` 中，即使 editable install 成功，shell 也依然找不到 `kittycode`。
+
+对于 `zsh`，可以把对应目录加入配置：
+
+```bash
+export PATH="$HOME/Library/Python/3.11/bin:$PATH"
+```
+
+然后重新加载 shell：
+
+```bash
+source ~/.zshrc
+```
+
+如果安装过程本身在往 `~/Library/Python/.../site-packages` 写 `.pth` 文件时就报权限错误，那要先修复本地 Python 环境权限，或者改用虚拟环境后再重新安装。
+
 ## 目录结构
 
 - `kittycode/agent.py`：核心代理循环
@@ -183,4 +227,4 @@ kittycode --interface anthropic --model claude-3-7-sonnet-latest
 python -m pytest -q
 ```
 
-当前测试主要覆盖导出 API、config.json 读取、provider 转换辅助逻辑、上下文压缩、会话辅助函数、默认工具注册表，以及 skill 发现与 prompt 注入逻辑。
+当前测试主要覆盖导出 API、config.json 读取、provider 转换辅助逻辑、上下文压缩、会话辅助函数、默认工具注册表，以及 skill 发现与 prompt 注入逻辑。

{kittycode-0.1.0 → kittycode-0.1.2}/kittycode/__init__.py

@@ -1,6 +1,6 @@
 """KittyCode - minimal AI coding agent."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 
 from kittycode.agent import Agent
 from kittycode.config import Config

kittycode-0.1.2/kittycode/agent.py

@@ -0,0 +1,166 @@
+"""Core agent loop.
+
+This is the heart of KittyCode.
+
+    user message -> LLM (with tools) -> tool calls? -> execute -> loop
+                                      -> text reply? -> return to user
+
+It keeps looping until the LLM responds with plain text, which means it is
+done working and ready to report back.
+"""
+
+import concurrent.futures
+import copy
+import inspect
+
+from .context import ContextManager
+from .interrupts import CancellationRequested
+from .llm import LLM
+from .prompt import system_prompt
+from .skills import load_skills
+from .tools import create_tool_instances, get_tool
+from .tools.agent import AgentTool
+from .tools.base import Tool
+
+
+class Agent:
+    def __init__(
+        self,
+        llm: LLM,
+        tools: list[Tool] | None = None,
+        max_context_tokens: int = 128_000,
+        max_rounds: int = 50,
+    ):
+        self.llm = llm
+        self.tools = list(tools) if tools is not None else create_tool_instances()
+        self.messages: list[dict] = []
+        self.context = ContextManager(max_tokens=max_context_tokens)
+        self.max_rounds = max_rounds
+        self.skills = []
+        self._system = ""
+        self.refresh_skills(force_reload=True)
+
+        for tool in self.tools:
+            if isinstance(tool, AgentTool):
+                tool._parent_agent = self
+
+    def _full_messages(self) -> list[dict]:
+        self.refresh_skills()
+        return [{"role": "system", "content": self._system}] + self.messages
+
+    def _tool_schemas(self) -> list[dict]:
+        return [tool.schema() for tool in self.tools]
+
+    def fork(self):
+        worker = Agent(
+            llm=self.llm.clone() if hasattr(self.llm, "clone") else self.llm,
+            tools=[type(tool)() for tool in self.tools],
+            max_context_tokens=self.context.max_tokens,
+            max_rounds=self.max_rounds,
+        )
+        worker.messages = copy.deepcopy(self.messages)
+        worker.skills = list(self.skills)
+        worker._system = self._system
+        return worker
+
+    def chat(self, user_input: str, on_token=None, on_tool=None, on_tool_output=None, cancel_event=None) -> str:
+        """Process one user message. May involve multiple LLM/tool rounds."""
+        self.messages.append({"role": "user", "content": user_input})
+        self.context.maybe_compress(self.messages, self.llm)
+
+        try:
+            self._raise_if_cancelled(cancel_event)
+
+            for _ in range(self.max_rounds):
+                self._raise_if_cancelled(cancel_event)
+                response = self.llm.chat(
+                    messages=self._full_messages(),
+                    tools=self._tool_schemas(),
+                    on_token=on_token,
+                    cancel_event=cancel_event,
+                )
+
+                if not response.tool_calls:
+                    self.messages.append(response.message)
+                    return response.content
+
+                self.messages.append(response.message)
+
+                if len(response.tool_calls) == 1:
+                    tool_call = response.tool_calls[0]
+                    if on_tool:
+                        on_tool(tool_call.name, tool_call.arguments)
+                    self._raise_if_cancelled(cancel_event)
+                    result = self._exec_tool(tool_call, cancel_event=cancel_event, on_output=on_tool_output)
+                    self.messages.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": tool_call.id,
+                            "content": result,
+                        }
+                    )
+                else:
+                    results = self._exec_tools_parallel(
+                        response.tool_calls,
+                        on_tool=on_tool,
+                        on_tool_output=on_tool_output,
+                        cancel_event=cancel_event,
+                    )
+                    for tool_call, result in zip(response.tool_calls, results):
+                        self.messages.append(
+                            {
+                                "role": "tool",
+                                "tool_call_id": tool_call.id,
+                                "content": result,
+                            }
+                        )
+
+                self.context.maybe_compress(self.messages, self.llm)
+
+            return "(reached maximum tool-call rounds)"
+        except CancellationRequested:
+            return "(interrupted)"
+
+    def _exec_tool(self, tool_call, cancel_event=None, on_output=None) -> str:
+        """Execute a single tool call and return the result string."""
+        self._raise_if_cancelled(cancel_event)
+        tool = get_tool(tool_call.name, self.tools)
+        if tool is None:
+            return f"Error: unknown tool '{tool_call.name}'"
+        try:
+            execute_kwargs = dict(tool_call.arguments)
+            parameters = inspect.signature(tool.execute).parameters
+            if on_output is not None and "stream_callback" in parameters:
+                execute_kwargs["stream_callback"] = lambda text: on_output(tool_call.name, text)
+            if cancel_event is not None and "cancel_event" in parameters:
+                execute_kwargs["cancel_event"] = cancel_event
+            return tool.execute(**execute_kwargs)
+        except TypeError as exc:
+            return f"Error: bad arguments for {tool_call.name}: {exc}"
+        except Exception as exc:
+            return f"Error executing {tool_call.name}: {exc}"
+
+    def _exec_tools_parallel(self, tool_calls, on_tool=None, on_tool_output=None, cancel_event=None) -> list[str]:
+        """Run multiple tool calls concurrently using threads."""
+        for tool_call in tool_calls:
+            if on_tool:
+                on_tool(tool_call.name, tool_call.arguments)
+        self._raise_if_cancelled(cancel_event)
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=8) as pool:
+            futures = [pool.submit(self._exec_tool, tool_call, cancel_event, on_tool_output) for tool_call in tool_calls]
+            return [future.result() for future in futures]
+
+    def reset(self):
+        """Clear conversation history."""
+        self.messages.clear()
+
+    def refresh_skills(self, force_reload: bool = False):
+        """Refresh cached skill metadata and rebuild the system prompt."""
+        self.skills = load_skills(force_reload=force_reload)
+        self._system = system_prompt(self.tools, self.skills)
+
+    @staticmethod
+    def _raise_if_cancelled(cancel_event):
+        if cancel_event is not None and cancel_event.is_set():
+            raise CancellationRequested()