krim 0.3.0__tar.gz

krim-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 batteryhob
+
+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.

krim-0.3.0/PKG-INFO

@@ -0,0 +1,334 @@
+Metadata-Version: 2.4
+Name: krim
+Version: 0.3.0
+Summary: Thin CLI agent. Trust the model, keep the harness light.
+Author: batteryhob
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/batteryhob/KRIM
+Project-URL: Repository, https://github.com/batteryhob/KRIM
+Project-URL: Issues, https://github.com/batteryhob/KRIM/issues
+Keywords: cli,agent,coding-agent,llm,anthropic,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic[vertex]>=0.39.0
+Requires-Dist: openai>=1.50.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: prompt_toolkit>=3.0.0
+Provides-Extra: harbor
+Requires-Dist: harbor>=0.1.0; extra == "harbor"
+Provides-Extra: vertex
+Requires-Dist: anthropic[vertex]>=0.39.0; extra == "vertex"
+Dynamic: license-file
+
+<table align="center"><tr><td>
+
+```
+                      ██╗  ██╗██████╗ ██╗███╗   ███╗
+      ●      ●        ██║ ██╔╝██╔══██╗██║████╗ ████║
+                      █████╔╝ ██████╔╝██║██╔████╔██║
+    ▄████◣◢████▄      ██╔═██╗ ██╔══██╗██║██║╚██╔╝██║
+ ◥▄████▀▀  ▀▀████▄◤   ██║  ██╗██║  ██║██║██║ ╚═╝ ██║
+    ▀▀        ▀▀      ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═╝     ╚═╝
+```
+
+</td></tr></table>
+
+<div align="center">
+
+**Trust the model. Keep the harness light.**
+
+[![Terminal-Bench](https://img.shields.io/badge/Terminal--Bench%202.0-71.9%25-brightgreen)](https://www.tbench.ai/leaderboard/terminal-bench/2.0)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+*A lightweight CLI coding agent. 6 tools, single loop, no sub-agents.*
+
+[Installation](#installation) • [Usage](#usage) • [Benchmark](#benchmark) • [Architecture](#architecture)
+
+</div>
+
+---
+
+## Philosophy
+
+| Principle | Description |
+|-----------|-------------|
+| **Trust the model** | Minimal system prompt. No scaffolding, no CoT wrappers, no sub-agents. Let the model decide. |
+| **One file, one job** | Every module does exactly one thing. Largest file is 330 lines. Average under 100. |
+| **Safe by default, always escapable** | deny > allow > ask. Every guardrail has an off switch. |
+
+## Benchmark
+
+<div align="center">
+
+### Terminal-Bench 2.0
+
+| Metric | Score |
+|--------|-------|
+| **Pass Rate** | 64/89 (71.9%) |
+| **Model** | Claude Opus 4.6 |
+| **Provider** | Vertex AI |
+
+</div>
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Requires Python 3.10+ and an API key for your chosen provider:
+
+```bash
+# Claude (Anthropic)
+export ANTHROPIC_API_KEY="sk-..."
+
+# OpenAI
+export OPENAI_API_KEY="sk-..."
+
+# Vertex AI (Google Cloud - recommended for high-volume)
+export VERTEXAI_LOCATION="us-east5"
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
+```
+
+## Usage
+
+```bash
+# Run krim (shows provider selection menu)
+krim
+# Select provider:
+#   [1] claude (Anthropic Claude)
+#   [2] openai (OpenAI)
+#   [3] vertex_ai (Google Vertex AI)
+
+# Single prompt (also shows provider menu)
+krim "fix the failing test in test_api.py"
+
+# Skip menu with --provider flag
+krim --provider claude "refactor this"
+krim --provider openai "add tests"
+krim --provider vertex_ai "deploy to prod"
+
+# Power user
+krim --max-turns 20 "large refactor"
+krim --skill deploy "ship it"
+krim --auto-commit "fix and commit"
+krim --no-safety "run anything"
+krim --verbose "debug mode"
+krim --log-dir ./logs "save conversation"
+```
+
+### Ralph Wiggum Loop
+
+Run the agent repeatedly until a condition passes. Each iteration starts fresh — state lives in git, not LLM memory.
+
+```bash
+# Loop until pytest passes (max 20 iterations)
+krim --loop --exit-on "pytest" "implement the PRD"
+
+# Limit iterations
+krim --loop --max-iterations 10 --exit-on "ruff check ." "fix all lint errors"
+```
+
+### Parallel Worktrees
+
+Leverage git worktrees to run multiple independent tasks simultaneously.
+
+```bash
+# 3 agents work in parallel, auto-merge on completion
+krim --parallel "add auth" "add payments" "add tests"
+
+# Keep branches separate for manual review
+krim --parallel --no-merge "feature A" "feature B"
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `bash` | Shell execution with persistent cwd. Safety rules enforced. |
+| `read` | File reading with line numbers. Supports offset/limit for large files. |
+| `write` | File writing with auto parent directory creation. |
+| `edit` | String replacement with exact → whitespace-normalized → fuzzy matching (0.8 threshold). |
+| `grep` | Regex content search. Uses ripgrep when available, Python fallback otherwise. |
+| `glob` | File pattern matching (e.g., `**/*.py`). Results sorted by modification time. |
+
+## Architecture
+
+```
+krim/
+├── __main__.py      # CLI entry, arg parsing, interactive/loop/parallel modes
+├── agent.py         # Core agent loop, doom loop detection, stats
+├── ui.py            # Banner, prompt_toolkit input
+├── prompt.py        # System prompt builder
+├── config.py        # Hierarchical config loader
+├── context.py       # Environment context (cwd, git, file tree)
+├── safety.py        # Bash command safety rules
+├── compaction.py    # Token tracking, conversation compression
+├── truncate.py      # Output truncation (head/tail)
+├── retry.py         # Exponential backoff
+├── git.py           # Auto-commit, undo, selective staging
+├── worktree.py      # Git worktree management for parallel execution
+├── skills.py        # Skill discovery and injection
+├── mcp.py           # MCP client (stdio, JSON-RPC)
+├── models/
+│   ├── base.py      # Abstract Model, ToolCall, ModelResponse
+│   ├── claude.py    # Anthropic Claude provider
+│   ├── openai.py    # OpenAI provider
+│   └── vertex.py    # Vertex AI provider
+└── tools/
+    ├── base.py      # Abstract Tool with auto schema generation
+    ├── bash.py      # Shell execution, persistent cwd
+    ├── read.py      # File reading with line numbers
+    ├── write.py     # File writing
+    ├── edit.py      # Fuzzy string replacement
+    ├── grep.py      # Regex search (ripgrep + fallback)
+    └── glob.py      # File pattern matching
+```
+
+### Loop Behavior
+
+```
+User Input
+    ↓
+[System Prompt + Context + History]
+    ↓
+Model → Text response?  → Done
+     → Tool calls?      → Execute each → Append results → Loop
+     → Doom loop 1st?   → Recovery nudge (keep tools, suggest different strategy)
+     → Doom loop 2nd?   → Force exit with summary
+     → Near max turns?  → Inject last-turn warning
+     → Max turns hit?   → Force exit with wrap-up request
+     → Token limit?     → Compress history and continue
+```
+
+Single loop. No routing, no planning phase, no sub-agents.
+
+### Double Confirmation
+
+When the agent responds with text only (no tool calls), KRIM asks for confirmation before exiting. This prevents premature exits when the agent says "I'll do X" but doesn't actually call a tool.
+
+```
+Agent: "I've completed the task."
+KRIM:  "Confirm by saying 'Task complete' or continue working."
+Agent: "Task complete."
+KRIM:  [exits]
+```
+
+If the agent says "I haven't finished yet" or "Let me continue", KRIM resets and lets it keep working.
+
+## Configuration
+
+Hierarchy: `~/.krim/` (global) < `.krim/` (project) < CLI flags.
+
+```
+.krim/
+├── config.json      # Settings
+├── KRIM.md          # Instructions injected into system prompt
+├── mcp.json         # MCP server config
+├── rules/
+│   └── *.md         # Additional rules
+└── skills/
+    └── <name>/
+        └── SKILL.md # Skill instructions
+```
+
+### config.json
+
+```json
+{
+  "max_turns": 10,
+  "auto_commit": false,
+  "ask_by_default": true,
+  "allow_commands": ["ls", "cat", "grep", "git status", "git diff", "pytest"],
+  "deny_patterns": ["rm -rf /", "> /dev/sda", "mkfs."],
+  "max_tokens": 16384,
+  "bash_timeout": 120,
+  "token_limit": 120000
+}
+```
+
+**Default models** (used when `--model` is not specified):
+| Provider | Default Model |
+|----------|---------------|
+| claude | claude-opus-4-6 |
+| openai | gpt-5.2 |
+| vertex_ai | claude-opus-4-6 |
+
+### Skills
+
+Reusable prompt packages. Activate with `--skill <name>`:
+
+```bash
+krim --skill deploy "ship the new feature"
+krim --list-skills
+```
+
+**SKILL.md format** ([Anthropic standard](https://github.com/anthropics/skills)):
+
+```markdown
+---
+name: my-skill
+description: What this skill does and when to use it
+---
+
+# Skill Content
+
+Instructions in markdown...
+```
+
+### MCP
+
+Connect external tool servers via [Model Context Protocol](https://modelcontextprotocol.io):
+
+```json
+{
+  "mcpServers": {
+    "web-search": {
+      "command": ["node", "search-server/index.js"],
+      "env": { "API_KEY": "..." }
+    }
+  }
+}
+```
+
+## Safety
+
+Commands pass through 3-stage checks: **deny > allow > ask**.
+
+- **deny**: Substring match on dangerous patterns. Blocked immediately.
+- **allow**: Word-boundary match on safe prefixes. Auto-approved.
+- **ask**: Everything else prompts for user confirmation.
+
+Disable with `--no-safety` or `"ask_by_default": false` in config.
+
+## Interactive Commands
+
+```
+/help      Show command help
+/tokens    Token usage and stats
+/compact   Force context compression
+/config    Show current configuration
+/undo      Revert last krim commit
+/verbose   Toggle verbose output
+exit       Quit
+```
+
+Arrow keys for history. Tab for command completion.
+
+## License
+
+MIT

krim-0.3.0/README.md

@@ -0,0 +1,300 @@
+<table align="center"><tr><td>
+
+```
+                      ██╗  ██╗██████╗ ██╗███╗   ███╗
+      ●      ●        ██║ ██╔╝██╔══██╗██║████╗ ████║
+                      █████╔╝ ██████╔╝██║██╔████╔██║
+    ▄████◣◢████▄      ██╔═██╗ ██╔══██╗██║██║╚██╔╝██║
+ ◥▄████▀▀  ▀▀████▄◤   ██║  ██╗██║  ██║██║██║ ╚═╝ ██║
+    ▀▀        ▀▀      ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═╝     ╚═╝
+```
+
+</td></tr></table>
+
+<div align="center">
+
+**Trust the model. Keep the harness light.**
+
+[![Terminal-Bench](https://img.shields.io/badge/Terminal--Bench%202.0-71.9%25-brightgreen)](https://www.tbench.ai/leaderboard/terminal-bench/2.0)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+*A lightweight CLI coding agent. 6 tools, single loop, no sub-agents.*
+
+[Installation](#installation) • [Usage](#usage) • [Benchmark](#benchmark) • [Architecture](#architecture)
+
+</div>
+
+---
+
+## Philosophy
+
+| Principle | Description |
+|-----------|-------------|
+| **Trust the model** | Minimal system prompt. No scaffolding, no CoT wrappers, no sub-agents. Let the model decide. |
+| **One file, one job** | Every module does exactly one thing. Largest file is 330 lines. Average under 100. |
+| **Safe by default, always escapable** | deny > allow > ask. Every guardrail has an off switch. |
+
+## Benchmark
+
+<div align="center">
+
+### Terminal-Bench 2.0
+
+| Metric | Score |
+|--------|-------|
+| **Pass Rate** | 64/89 (71.9%) |
+| **Model** | Claude Opus 4.6 |
+| **Provider** | Vertex AI |
+
+</div>
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Requires Python 3.10+ and an API key for your chosen provider:
+
+```bash
+# Claude (Anthropic)
+export ANTHROPIC_API_KEY="sk-..."
+
+# OpenAI
+export OPENAI_API_KEY="sk-..."
+
+# Vertex AI (Google Cloud - recommended for high-volume)
+export VERTEXAI_LOCATION="us-east5"
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
+```
+
+## Usage
+
+```bash
+# Run krim (shows provider selection menu)
+krim
+# Select provider:
+#   [1] claude (Anthropic Claude)
+#   [2] openai (OpenAI)
+#   [3] vertex_ai (Google Vertex AI)
+
+# Single prompt (also shows provider menu)
+krim "fix the failing test in test_api.py"
+
+# Skip menu with --provider flag
+krim --provider claude "refactor this"
+krim --provider openai "add tests"
+krim --provider vertex_ai "deploy to prod"
+
+# Power user
+krim --max-turns 20 "large refactor"
+krim --skill deploy "ship it"
+krim --auto-commit "fix and commit"
+krim --no-safety "run anything"
+krim --verbose "debug mode"
+krim --log-dir ./logs "save conversation"
+```
+
+### Ralph Wiggum Loop
+
+Run the agent repeatedly until a condition passes. Each iteration starts fresh — state lives in git, not LLM memory.
+
+```bash
+# Loop until pytest passes (max 20 iterations)
+krim --loop --exit-on "pytest" "implement the PRD"
+
+# Limit iterations
+krim --loop --max-iterations 10 --exit-on "ruff check ." "fix all lint errors"
+```
+
+### Parallel Worktrees
+
+Leverage git worktrees to run multiple independent tasks simultaneously.
+
+```bash
+# 3 agents work in parallel, auto-merge on completion
+krim --parallel "add auth" "add payments" "add tests"
+
+# Keep branches separate for manual review
+krim --parallel --no-merge "feature A" "feature B"
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `bash` | Shell execution with persistent cwd. Safety rules enforced. |
+| `read` | File reading with line numbers. Supports offset/limit for large files. |
+| `write` | File writing with auto parent directory creation. |
+| `edit` | String replacement with exact → whitespace-normalized → fuzzy matching (0.8 threshold). |
+| `grep` | Regex content search. Uses ripgrep when available, Python fallback otherwise. |
+| `glob` | File pattern matching (e.g., `**/*.py`). Results sorted by modification time. |
+
+## Architecture
+
+```
+krim/
+├── __main__.py      # CLI entry, arg parsing, interactive/loop/parallel modes
+├── agent.py         # Core agent loop, doom loop detection, stats
+├── ui.py            # Banner, prompt_toolkit input
+├── prompt.py        # System prompt builder
+├── config.py        # Hierarchical config loader
+├── context.py       # Environment context (cwd, git, file tree)
+├── safety.py        # Bash command safety rules
+├── compaction.py    # Token tracking, conversation compression
+├── truncate.py      # Output truncation (head/tail)
+├── retry.py         # Exponential backoff
+├── git.py           # Auto-commit, undo, selective staging
+├── worktree.py      # Git worktree management for parallel execution
+├── skills.py        # Skill discovery and injection
+├── mcp.py           # MCP client (stdio, JSON-RPC)
+├── models/
+│   ├── base.py      # Abstract Model, ToolCall, ModelResponse
+│   ├── claude.py    # Anthropic Claude provider
+│   ├── openai.py    # OpenAI provider
+│   └── vertex.py    # Vertex AI provider
+└── tools/
+    ├── base.py      # Abstract Tool with auto schema generation
+    ├── bash.py      # Shell execution, persistent cwd
+    ├── read.py      # File reading with line numbers
+    ├── write.py     # File writing
+    ├── edit.py      # Fuzzy string replacement
+    ├── grep.py      # Regex search (ripgrep + fallback)
+    └── glob.py      # File pattern matching
+```
+
+### Loop Behavior
+
+```
+User Input
+    ↓
+[System Prompt + Context + History]
+    ↓
+Model → Text response?  → Done
+     → Tool calls?      → Execute each → Append results → Loop
+     → Doom loop 1st?   → Recovery nudge (keep tools, suggest different strategy)
+     → Doom loop 2nd?   → Force exit with summary
+     → Near max turns?  → Inject last-turn warning
+     → Max turns hit?   → Force exit with wrap-up request
+     → Token limit?     → Compress history and continue
+```
+
+Single loop. No routing, no planning phase, no sub-agents.
+
+### Double Confirmation
+
+When the agent responds with text only (no tool calls), KRIM asks for confirmation before exiting. This prevents premature exits when the agent says "I'll do X" but doesn't actually call a tool.
+
+```
+Agent: "I've completed the task."
+KRIM:  "Confirm by saying 'Task complete' or continue working."
+Agent: "Task complete."
+KRIM:  [exits]
+```
+
+If the agent says "I haven't finished yet" or "Let me continue", KRIM resets and lets it keep working.
+
+## Configuration
+
+Hierarchy: `~/.krim/` (global) < `.krim/` (project) < CLI flags.
+
+```
+.krim/
+├── config.json      # Settings
+├── KRIM.md          # Instructions injected into system prompt
+├── mcp.json         # MCP server config
+├── rules/
+│   └── *.md         # Additional rules
+└── skills/
+    └── <name>/
+        └── SKILL.md # Skill instructions
+```
+
+### config.json
+
+```json
+{
+  "max_turns": 10,
+  "auto_commit": false,
+  "ask_by_default": true,
+  "allow_commands": ["ls", "cat", "grep", "git status", "git diff", "pytest"],
+  "deny_patterns": ["rm -rf /", "> /dev/sda", "mkfs."],
+  "max_tokens": 16384,
+  "bash_timeout": 120,
+  "token_limit": 120000
+}
+```
+
+**Default models** (used when `--model` is not specified):
+| Provider | Default Model |
+|----------|---------------|
+| claude | claude-opus-4-6 |
+| openai | gpt-5.2 |
+| vertex_ai | claude-opus-4-6 |
+
+### Skills
+
+Reusable prompt packages. Activate with `--skill <name>`:
+
+```bash
+krim --skill deploy "ship the new feature"
+krim --list-skills
+```
+
+**SKILL.md format** ([Anthropic standard](https://github.com/anthropics/skills)):
+
+```markdown
+---
+name: my-skill
+description: What this skill does and when to use it
+---
+
+# Skill Content
+
+Instructions in markdown...
+```
+
+### MCP
+
+Connect external tool servers via [Model Context Protocol](https://modelcontextprotocol.io):
+
+```json
+{
+  "mcpServers": {
+    "web-search": {
+      "command": ["node", "search-server/index.js"],
+      "env": { "API_KEY": "..." }
+    }
+  }
+}
+```
+
+## Safety
+
+Commands pass through 3-stage checks: **deny > allow > ask**.
+
+- **deny**: Substring match on dangerous patterns. Blocked immediately.
+- **allow**: Word-boundary match on safe prefixes. Auto-approved.
+- **ask**: Everything else prompts for user confirmation.
+
+Disable with `--no-safety` or `"ask_by_default": false` in config.
+
+## Interactive Commands
+
+```
+/help      Show command help
+/tokens    Token usage and stats
+/compact   Force context compression
+/config    Show current configuration
+/undo      Revert last krim commit
+/verbose   Toggle verbose output
+exit       Quit
+```
+
+Arrow keys for history. Tab for command completion.
+
+## License
+
+MIT

krim-0.3.0/krim/__init__.py

@@ -0,0 +1,3 @@
+"""krim - thin CLI agent. trust the model, keep the harness light."""
+
+__version__ = "0.3.0"