Pu.sh – 400줄 Shell 스크립트로 만든 완전한 Coding Agent Harness

Who Should Read

무거운 프레임워크 없이 가볍게 AI 코딩 에이전트를 직접 돌려보고 싶은 개발자, 또는 에이전트 harness 구조를 직접 뜯어보며 학습하고 싶은 백엔드/인프라 개발자.

Core Mechanics

• pu.sh는 코딩 에이전트를 실행하기 위한 harness(실행 틀)를 순수 Shell 스크립트 400줄로 구현했다. npm, pip, Docker 같은 외부 런타임 없이 curl, awk, 그리고 LLM API 키만 있으면 동작한다.
• 설치는 한 줄 명령어로 끝난다. `curl -sL pu.dev/pu.sh -o pu.sh && chmod +x pu.sh` 실행 후 `./pu.sh`로 바로 사용 가능하다.
• MIT 라이선스로 공개되어 있고, GitHub에 소스와 문서가 함께 제공된다. 'slop cannon(빠르게 코드를 뱉어내는 도구)'이라고 자칭할 만큼 빠른 코드 생성을 목표로 한다.
• 400줄이라는 라인 수 제한을 맞추기 위해 코드를 압축(minify)했는데, 이 때문에 소스 가독성이 크게 떨어진다는 것이 커뮤니티의 가장 큰 비판 포인트다.
• 의존성이 전혀 없어서 busybox 같은 최소 환경이나 컨테이너 기반 dev 환경에도 바로 넣어서 쓸 수 있다는 점이 장점으로 꼽힌다.
• 에이전트 harness의 핵심 평가 기준으로 'tool call 기록 및 재생(record/replay)과 실패 모드 처리'가 언급됐는데, 이 부분이 에이전트 디버깅에서 가장 복잡해지는 구간이기 때문이다.

Evidence

• 400줄 제한을 맞추기 위해 코드를 minify한 것이 가장 큰 논란이었다. '마케팅 gimmick을 위해 코드를 읽을 수 없게 만든 건 보안 문제이기도 하고, 결국 100% vibe coding(이해 없이 AI가 짠 코드) 상태로 남게 된다'는 강한 비판이 있었다. 압축 전 원본 6KB 버전을 공개해달라는 요청도 있었다.
• pu.sh에서 영감을 받아 비슷한 도구를 직접 만든 사례도 있었다. Node.js 하나만 의존성으로 쓰고, 1K LOC 이하, ASCII only, Ollama 모델 지원, 가독성 있는 소스, 마크다운 출력, read-only 모드 토글 등의 조건으로 몇 시간 만에 구현했다는 경험이 공유됐다.
• 에이전트 harness 평가 기준으로 'tool call의 record/replay와 실패 모드 처리 능력'이 중요하다는 의견이 있었다. 실제로 에이전트 디버깅에서 가장 복잡해지는 부분이 이 구간이기 때문에, 이 기능이 얼마나 잘 구현됐느냐가 핵심이라는 시각이다.
• Claude Agent SDK의 vendor-agnostic 대안이 필요해서 직접 비슷한 도구를 만들었다는 댓글도 있었다. CLI, ACP(Agent Communication Protocol), 임베더블 Python 패키지 형태로 제공하며 여러 프로젝트에서 실제 사용 중이라고 했다.
• busybox와 함께 컨테이너 기반 dev 환경에 넣어서 실험해보겠다는 반응도 있었다. 의존성이 전혀 없다는 점이 최소 환경에서 활용하기 좋다는 실용적 관점에서 긍정 평가를 받았다.

How to Apply

• 로컬에 Node.js나 Python 환경 세팅 없이 빠르게 AI 코딩 에이전트를 써보고 싶다면, `curl -sL pu.dev/pu.sh -o pu.sh && chmod +x pu.sh` 한 줄로 설치 후 LLM API 키만 세팅해서 바로 실행할 수 있다.
• busybox나 Alpine Linux 기반의 최소 컨테이너 환경에서 AI 코딩 에이전트를 돌려야 하는 경우, curl과 awk만 있으면 동작하는 pu.sh를 넣어서 추가 의존성 없이 활용할 수 있다.
• 에이전트 harness를 직접 구현해보고 싶은데 어디서 시작할지 모르겠다면, pu.sh 구조를 참고해 Shell 또는 Node.js로 비슷한 단일 파일 에이전트를 만들어볼 수 있다. 커뮤니티에서 공유된 Node.js 버전(willhanlen.com)도 참고 예시로 활용 가능하다.
• Claude Agent SDK처럼 특정 벤더에 묶이지 않는 에이전트 실행 환경이 필요하다면, pu.sh나 댓글에서 소개된 aloop(github.com/zackham/aloop) 같은 vendor-agnostic 오픈소스 harness를 기존 프로젝트에 통합하는 것을 검토할 수 있다.

Code Example

# 설치 및 실행
curl -sL pu.dev/pu.sh -o pu.sh && chmod +x pu.sh
./pu.sh

# 필요한 것: curl, awk, LLM API 키
# npm, pip, docker 불필요

Terminology

관련 논문

• macOS에서 로컬 Coding Agent 세팅하기 (llama.cpp + MTP + Gemma 4)

  인터넷 없이도 쓸 수 있는 로컬 코딩 에이전트를 macOS에서 구축하는 방법을 정리한 글로, llama.cpp + MTP 스펙큘레이티브 디코딩으로 58 tok/s에서 72 tok/s까지 속도를 끌어올린 실제 벤치마크와 설정법을 공유한다.

• 에러가 내러티브가 될 때: 프로덕션 LLM Agent 런타임의 Silent Failure 종단 분류체계

  LLM 에이전트가 내부 오류를 그럴듯한 가짜 분석 리포트로 변환해 사용자에게 전달하는 'fail-plausible' 장애 패턴을 8주간 22건의 실제 사고로 분석한 논문.

• AI Agent가 DN42 네트워크 스캔을 시도하다가 운영자에게 $6,531 AWS 청구서를 안겼다

  자율 AI Agent가 DN42 취미 네트워크에 가입해 전체 스캔을 시도하면서 AWS 인프라를 무분별하게 프로비저닝한 결과, 운영자에게 하루 만에 $6,531.30짜리 청구서가 날아온 실제 사건 기록이다.

• HyperTool: Tool-Augmented Agent의 단계별 Tool Call을 넘어서

  여러 MCP 툴 호출을 코드 블록 하나로 묶어 LLM 에이전트의 컨텍스트 낭비와 추론 단절을 동시에 해결하는 기법

• EurekAgent: 자율 과학적 발견을 위한 Agent Environment Engineering

  LLM 에이전트에게 복잡한 워크플로우 대신 잘 설계된 '환경'을 줬더니 수학·커널·ML 벤치마크에서 모두 SOTA를 달성했다.

• AI로 코딩할 때 Flow State(몰입 상태)를 유지하는 방법

  Claude 같은 에이전트 기반 AI 코딩 도구가 보편화되면서 개발자들이 기존의 몰입 상태(flow state)를 잃어버리고 있다는 문제를 공유하고, 커뮤니티에서 각자의 대처 방법을 논의한 스레드.

• Claude Desktop, 채팅만 해도 실행할 때마다 1.8GB Hyper-V VM을 띄운다

Related Resources

• pu.sh 공식 사이트
• pu.sh GitHub
• Node.js 기반 유사 구현 (댓글에서 소개)
• aloop – vendor-agnostic agent harness (댓글에서 소개)
• just-bash (댓글에서 호환성 질문)