<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
