krim 0.3.0

Thin CLI agent. Trust the model, keep the harness light.

██╗ ██╗██████╗ ██╗███╗ ███╗ ● ● ██║ ██╔╝██╔══██╗██║████╗ ████║ █████╔╝ ██████╔╝██║██╔████╔██║ ▄████◣◢████▄ ██╔═██╗ ██╔══██╗██║██║╚██╔╝██║ ◥▄████▀▀ ▀▀████▄◤ ██║ ██╗██║ ██║██║██║ ╚═╝ ██║ ▀▀ ▀▀ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝╚═╝ ╚═╝

Trust the model. Keep the harness light.

A lightweight CLI coding agent. 6 tools, single loop, no sub-agents.

Installation • Usage • Benchmark • Architecture

---

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

Terminal-Bench 2.0

Metric	Score
Pass Rate	64/89 (71.9%)
Model	Claude Opus 4.6
Provider	Vertex AI

Installation

pip install -e .

Requires Python 3.10+ and an API key for your chosen provider:

# 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

# 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.

# 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.

# 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

{
  "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>:

krim --skill deploy "ship the new feature"
krim --list-skills

SKILL.md format (Anthropic standard):

---
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:

{
  "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