___ ___ ___ _ _ ______ _____
| _ \/ __| __| \| |___/ __\ \ / / __|
| _/ (__| _|| .` |___\__ \\ \/\/ /| _|
|_| \___|___|_|\_| |___/ \_/\_/ |___|
Peen-SWE
Compact, workshop-forged terminal agent built to shape and refine code with zero black-box bloat.
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
--yolomode 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:
- Built-in defaults (
src/peen/config/peen.yaml) - Local workspace config (
./peen.yaml) - CLI overrides (
-c key=valueor--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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.