Skip to main content
  ___  ___ ___ _  _     ______      _____ 
 | _ \/ __| __| \| |___/ __\ \    / / __|
 |  _/ (__| _|| .` |___\__ \\ \/\/ /| _|  
 |_|  \___|___|_|\_|   |___/ \_/\_/ |___| 

Peen-SWE

Compact, workshop-forged terminal agent built to shape and refine code with zero black-box bloat.

License: MIT Python 3.10+ MCP Ready SWE-bench Verified PyPI CI

Quick Start • Why Peen-SWE • MCP Superpowers • Configuration • Credits & Attribution


🔨 Why Peen-SWE?

Most AI coding assistants have become heavy, opaque black boxes filled with proprietary scaffolding, silent prompt injections, and rigid execution harnesses.

Like a ball-peen hammer in a master craftsman's workshop, Peen-SWE is built to do one thing with surgical precision: shape, anneal, and refine code directly in your terminal without getting in your way.

  • Ultra-Transparent Control Flow: The entire agent loop fits in readable, unbloated Python. No complex agent graphs, no buried telemetry, and no magic abstractions.
  • Dual Execution Engine: Pairs native, stateless subshell Bash commands with standardized Model Context Protocol (MCP) tool discovery and calling.
  • Human-in-the-Loop Safeguards: Displays exact shell commands and MCP calls with interactive confirmation before execution, or toggle into autonomous --yolo mode when you trust the run.
  • Proven Benchmark Pedigree: Inherits the battle-tested, linear SWE-bench architecture that solves >74% of real-world GitHub issues.
  • Model Agnostic: Works out of the box with Claude 3.7 / 3.5 Sonnet, GPT-4o, DeepSeek-R1, Qwen, or local models via LiteLLM, Ollama, OpenRouter, and Portkey.

⚡ Architecture

                       ┌──────────────────────┐
                       │     User Prompt      │
                       └──────────┬───────────┘
                                  │
                                  ▼
                       ┌──────────────────────┐
                       │   Peen-SWE Agent     │ ◄── [peen.yaml]
                       │ (Minimal Control Loop│
                       └──────────┬───────────┘
                                  │
         ┌────────────────────────┴────────────────────────┐
         ▼                                                 ▼
┌──────────────────┐                              ┌──────────────────┐
│  Bash Subshell   │                              │  MCP Stdio Hub   │
│ (Local / Docker) │                              │ (ClientSession)  │
└────────┬─────────┘                              └────────┬─────────┘
         │                                                 │
   [ls, git, edit, tests]                        [sqlite, fetch, custom APIs]
         │                                                 │
         └────────────────────────┬────────────────────────┘
                                  │ Observation Messages
                                  ▼
                       ┌──────────────────────┐
                       │   Next Action Loop   │
                       └──────────────────────┘

🚀 Quick Start

1. Installation & Usage

Run instantly with uvx (no install required):

# Run directly from PyPI (once published)
uvx peen

# Or run directly from GitHub before publishing
uvx --from git+https://github.com/sobhit-singh/peen-swe peen

Install via pip:

# Install with Model Context Protocol (MCP) support
pip install "peen[mcp]"

# Or install editable from source
git clone https://github.com/sobhit-singh/peen-swe.git
cd peen-swe
pip install -e ".[mcp]"

2. Configure Your API Key

Set the API key for your model of choice:

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI
export OPENAI_API_KEY="sk-..."

# OpenRouter
export OPENROUTER_API_KEY="sk-or-..."

3. Launch Peen-SWE

Run the interactive terminal interface:

peen

Or pass a specific task and model directly:

peen -m anthropic/claude-3-7-sonnet-20250219 -t "Fix bug in auth middleware where token expiration throws 500"

To run autonomously without manual confirmation prompts:

peen -y -t "Write unit tests for utils/date_parser.py and make sure they pass"

🔌 MCP Superpowers

Peen-SWE natively connects to any local or remote Model Context Protocol (MCP) server via standard stdio pipes.

All MCP tools are automatically namespaced as {server_name}__{tool_name} to prevent name collisions with standard shell commands.

Defining MCP Servers in peen.yaml

Create a peen.yaml in your workspace or home directory:

mcp:
  servers:
    # Query databases directly without manual shell pipelines
    db:
      command: "uvx"
      args: ["mcp-server-sqlite", "--db-path", "./analytics.db"]

    # Provide safe file access outside current repo
    docs:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "../shared-docs"]

    # Web browsing & documentation fetcher
    web:
      command: "uvx"
      args: ["mcp-server-fetch"]

When you start peen, it automatically connects all servers, introspects their tool definitions, registers them with the model, and routes execution through an isolated async thread pool.


⚙️ Configuration

Peen-SWE supports hierarchical configuration:

  1. Built-in defaults (src/peen/config/peen.yaml)
  2. Local workspace config (./peen.yaml)
  3. CLI overrides (-c key=value or --mcp-config <path>)
# Run with a dedicated MCP config file
peen --mcp-config ./my_tools.yaml

# Set a hard cost limit in USD
peen -l 2.50 -t "Refactor the payment webhook handler"

📋 CLI Reference

Flag Short Description
--model -m Model name (e.g. anthropic/claude-3-7-sonnet, openai/gpt-4o, ollama/deepseek-r1)
--task -t Problem statement or task to solve
--yolo -y Autonomous mode (skip confirmation prompts)
--config -c Config spec path, file, or key=value override
--mcp-config Path to standalone JSON/YAML MCP server configuration
--cost-limit -l Cost limit in USD (set 0 to disable)
--output -o Output trajectory file path (.traj.json)

📄 License

This project is licensed under the MIT License.

Metadata

Release files for peen 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for peen 1.0.0
File Size Uploaded Provenance Actions
peen-1.0.0.tar.gz 73.2 kB With provenance Details for peen-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for peen 1.0.0
File Interpreter ABI Platform Actions
peen-1.0.0-py3-none-any.whl Python 3 none any Details for peen-1.0.0-py3-none-any.whl

Total release size: 192.2 kB

Release files / peen-1.0.0.tar.gz

Download URL peen-1.0.0.tar.gz
Size 73.2 kB
Tags Source
SHA-256 checksum
How to use checksums
cfb62654b7ccfba04df3c40197fca0d88193cb55a291d419e4f3669e27f3893b
BLAKE2b-256 checksum
How to use checksums
2587b27df65a7aeb37f184643a3ba91038f5023b618b6c383b5713be0d0b3eef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / peen-1.0.0-py3-none-any.whl

Download URL peen-1.0.0-py3-none-any.whl
Size 118.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d731482de007b892345931e9e2cae322944b8ec44800d456db1a97e8174a477f
BLAKE2b-256 checksum
How to use checksums
a3075aaa9801237662c77e8ea1c0c591a90a60213cf8a04c5cafc1e634aa3290
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for peen 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for peen-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page