kittycode 0.1.0__tar.gz

kittycode-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.DS_Store
+dist/
+.pytest_cache/
+findings.md
+progress.md
+task_plan.md

kittycode-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jimmy Ye
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kittycode-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: kittycode
+Version: 0.1.0
+Summary: Minimal AI coding agent with a simple tool loop.
+License: MIT
+License-File: LICENSE
+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'

kittycode-0.1.0/README.md

@@ -0,0 +1,186 @@
+# 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.
+- 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
+```
+
+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.
+
+## 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/README_CN.md

@@ -0,0 +1,186 @@
+# KittyCode
+
+KittyCode 是一个运行在终端里的轻量级 AI 编程代理，目标是在尽量精简代码的前提下保留清晰、直接的核心运行逻辑，包括主代理循环、本地工具调用、上下文压缩、命令行交互，以及对 OpenAI 兼容接口和 Anthropic 接口的支持。
+
+## 项目背景
+
+KittyCode 的基本工作方式如下：
+
+- 用户输入先通过当前配置的模型接口发送出去。
+- 模型可以直接回答，也可以发起工具调用。
+- 本地执行工具后，再把结果回填给模型继续推理。
+- 直到模型返回普通文本，当前任务才结束。
+
+这个项目刻意保持小而清晰，只保留最核心的运行时能力，包括代理主循环、命令行界面、会话保存、上下文压缩，以及默认工具集。
+
+## 功能特点
+
+- 保留核心 agent loop，并支持多工具并行执行。
+- LLM 适配层同时支持 OpenAI 兼容接口和 Anthropic 接口。
+- 内置 Bash、读文件、写文件、精确替换编辑、Glob 搜索、Grep 搜索、子代理等工具。
+- 启动时自动扫描 `~/.kittycode/skills`，并在每轮系统 prompt 开头注入可用 skill 列表。
+- 支持交互式 REPL 和单次命令模式。
+- 支持长会话上下文压缩。
+- 支持保存和恢复历史会话。
+
+## 环境要求
+
+- Python 3.10 及以上
+- OpenAI 兼容接口或 Anthropic 接口所需的 API Key
+
+## 安装方法
+
+进入项目目录后，以可编辑模式安装：
+
+```bash
+cd KittyCode
+python -m pip install -e .
+```
+
+如果还要安装测试依赖：
+
+```bash
+python -m pip install -e .[dev]
+```
+
+## 配置说明
+
+KittyCode 启动时会从 `~/.kittycode/config.json` 读取配置。
+
+支持的字段包括：
+
+- `interface`：`openai` 或 `anthropic`
+- `api_key`
+- `model`
+- `base_url`
+- `max_tokens`
+- `temperature`
+- `max_context`
+
+OpenAI 兼容接口示例：
+
+```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 接口示例：
+
+```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
+}
+```
+
+如果需要，也可以通过命令行参数临时覆盖这些配置，例如 `--model`、`--interface`、`--base-url`、`--api-key`。
+
+## Skills 机制
+
+KittyCode 启动时会扫描 `~/.kittycode/skills` 目录。每个 skill 使用一个独立文件夹，文件夹顶层需要有一个 `SKILL.md`。
+
+目录结构示例：
+
+```text
+~/.kittycode/skills/
+	example-skill/
+		SKILL.md
+		other-files...
+```
+
+运行时会从每个 `SKILL.md` 开头读取 `name` 和 `description`，并把得到的 skill 列表缓存在进程内存中。每一轮对话时，系统 prompt 最前面都会包含以下字段：
+
+- `name`
+- `description`
+- `path`
+
+这样模型就能先看到本地有哪些 skill，再按需读取对应目录下的 `SKILL.md` 和其他相关文件。
+
+每轮对话前，KittyCode 都会检查 skill 目录是否发生变化；如果新增或修改了 skill，会自动刷新内存缓存，因此不需要重启进程。
+
+你也可以在 CLI 中直接通过 `/<skill 名称>` 使用某个已加载的 skill。
+
+- `/<skill 名称>`：选中该 skill，下一条普通输入会自动带上这个 skill。
+- `/<skill 名称> <任务>`：立即用这个 skill 执行当前请求。
+
+## 使用方法
+
+启动交互式终端界面：
+
+```bash
+kittycode
+```
+
+也可以直接通过模块启动：
+
+```bash
+python -m kittycode
+```
+
+单次执行一个提示词并退出：
+
+```bash
+kittycode -p "Explain the project structure"
+```
+
+恢复历史会话：
+
+```bash
+kittycode -r session_1234567890
+```
+
+临时覆盖模型、接口类型或接口地址：
+
+```bash
+kittycode --interface anthropic --model claude-3-7-sonnet-latest
+```
+
+## 交互命令
+
+在 REPL 中可用的命令有：
+
+- `/help`
+- `/reset`
+- `/skills`
+- `/<skill 名称>`
+- `/model <name>`
+- `/tokens`
+- `/compact`
+- `/save`
+- `/sessions`
+- `/quit`
+
+`/skills` 命令会在检测到 skill 目录变化时刷新本地缓存，并输出当前已加载的 skill 列表。
+当输入以 `/` 开头时，CLI 还会根据前缀自动补全可用命令和 skill。
+
+## 目录结构
+
+- `kittycode/agent.py`：核心代理循环
+- `kittycode/llm.py`：流式 LLM 封装
+- `kittycode/context.py`：上下文压缩
+- `kittycode/cli.py`：交互式与单次命令入口
+- `kittycode/session.py`：会话持久化
+- `kittycode/tools/`：内置工具集合
+- `tests/`：核心运行时与工具测试
+
+## 开发与测试
+
+运行测试：
+
+```bash
+python -m pytest -q
+```
+
+当前测试主要覆盖导出 API、config.json 读取、provider 转换辅助逻辑、上下文压缩、会话辅助函数、默认工具注册表，以及 skill 发现与 prompt 注入逻辑。

kittycode-0.1.0/kittycode/__init__.py

@@ -0,0 +1,10 @@
+"""KittyCode - minimal AI coding agent."""
+
+__version__ = "0.1.0"
+
+from kittycode.agent import Agent
+from kittycode.config import Config
+from kittycode.llm import LLM
+from kittycode.tools import ALL_TOOLS
+
+__all__ = ["Agent", "Config", "LLM", "ALL_TOOLS", "__version__"]

kittycode-0.1.0/kittycode/__main__.py

@@ -0,0 +1,3 @@
+from kittycode.cli import main
+
+main()

kittycode-0.1.0/kittycode/agent.py

@@ -0,0 +1,125 @@
+"""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
+
+from .context import ContextManager
+from .llm import LLM
+from .prompt import system_prompt
+from .skills import load_skills
+from .tools import ALL_TOOLS, 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 = tools if tools is not None else ALL_TOOLS
+        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 chat(self, user_input: str, on_token=None, on_tool=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)
+
+        for _ in range(self.max_rounds):
+            response = self.llm.chat(
+                messages=self._full_messages(),
+                tools=self._tool_schemas(),
+                on_token=on_token,
+            )
+
+            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)
+                result = self._exec_tool(tool_call)
+                self.messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": tool_call.id,
+                        "content": result,
+                    }
+                )
+            else:
+                results = self._exec_tools_parallel(response.tool_calls, on_tool)
+                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)"
+
+    def _exec_tool(self, tool_call) -> str:
+        """Execute a single tool call and return the result string."""
+        tool = get_tool(tool_call.name)
+        if tool is None:
+            return f"Error: unknown tool '{tool_call.name}'"
+        try:
+            return tool.execute(**tool_call.arguments)
+        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) -> 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)
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=8) as pool:
+            futures = [pool.submit(self._exec_tool, tool_call) 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)