he-yufeng/CoreCoder

CoreCoder – 작고 읽기 쉬운 코딩 에이전트 엔진

정의 – CoreCoder는 코드 편집 AI 에이전트를 순수 파이썬으로 구현한 2,800줄짜리 코드입니다. '코딩 어시스턴트'라는 개념을 핵심 요소로 축소합니다: 사용자 프롬프트를 LLM에 보내고, 모델이 몇 가지 도구(파일 읽기/쓰기, 셸, grep 등)를 호출하게 하고, 도구 결과를 대화에 다시 피드백하고, 모델이 최종 답변을 반환할 때까지 반복하는 while 루프입니다. 이 모든 것은 오후에 읽을 수 있을 만큼 간결하고 포크하기 쉽게 작성되었습니다.

중요성 – 대부분의 상용 에이전트(Claude Code, Cursor 등)는 수십만 줄의 폐쇄된 코드 뒤에 핵심 로직을 숨깁니다. CoreCoder는 모델 래퍼, 비용 추적, 3계층 컨텍스트 압축, 병렬 도구 실행, 하위 에이전트 생성, 권한 프롬프트, REPL 등 전체 파이프라인을 하나의 잘 주석 처리된 코드베이스로 공개합니다. 이는 실제 코딩 에이전트가 어떻게 작동하는지 이해하거나 맞춤형 버전을 구축하려는 모든 사람에게 실용적인 참고 자료가 됩니다.

주요 구성 요소

• agent.py – 대화를 이끄는 메인 루프(약 240줄).
• llm.py – 스트리밍 OpenAI 호환 클라이언트, 재시도 로직, 토큰 비용 계산.
• context.py – 3계층 컨텍스트 정리(기계적 절단, 모델 요약, 적극적 잘라내기).
• tools/ – 8개의 내장 도구(bash, read_file, write_file, edit_file, glob, grep, todo_write, agent) 및 선택적 MCP 확장.
• cli.py – 슬래시 명령어(/model, /plan, /undo, /tokens 등)를 지원하는 대화형 REPL.
• hooks.py, permissions.py, checkpoints.py – 안전 게이트, 동의 처리, 실행 취소 지원.

사용 방법

# 클론 후 편집 모드로 설치
git clone https://github.com/he-yufeng/CoreCoder
cd CoreCoder
pip install -e .

# 또는 릴리스된 패키지 설치
pip install corecoder

# LLM 자격 증명 설정 (OpenAI 예시)
export OPENAI_API_KEY=sk-...
# 선택: 모델 선택
export CORECODER_MODEL=gpt-5.5   # 기본값

# 대화형 REPL 실행
corecoder

# 일회성 사용 (함수에 오류 처리 추가 후 종료)
corecoder -p "parse_config()에 오류 처리 추가"

REPL은 --yes로 시작하지 않는 한 변경을 가하는 도구(write_file, edit_file, bash, 하위 에이전트)가 실행되기 전에 동의를 요청합니다.

확장 / 포크

1. 모델 교체 – CORECODER_MODEL 환경 변수를 변경하거나 사용자 정의 LLM 인스턴스를 전달하기만 하면 됩니다.
2. 도구 추가 – tools/base.py를 상속하는 새 파일을 tools/에 만들고 run()을 구현한 후 agent.py에 등록하세요.
3. 시스템 프롬프트 편집 – prompt.py(41줄)를 수정하여 에이전트의 성격이나 지침을 변경하세요.
4. 라이브러리로 임베드 –

   from corecoder import Agent, LLM
   llm = LLM(model="deepseek-chat", api_key="sk-…")
   print(Agent(llm=llm).chat("이 저장소의 모든 TODO 주석을 나열해줘"))
   

5. 에세이 탐색 – 저장소에는 각 하위 시스템을 줄 단위로 설명하는 8부작 이중 언어 '소스 읽기 시리즈'가 포함되어 있습니다.

대상 독자 –

• 코딩 에이전트를 구축하거나 연구하기 위한 구체적이고 오픈 소스 참고 자료를 원하는 연구자나 엔지니어.
• 도구 세트를 사용자 정의하거나, RAG를 추가하거나, 엔진을 더 큰 IDE 유사 제품에 통합하는 데 관심이 있는 개발자.
• LLM 기반 에이전트를 가르치는 교육자; 최소한의 코드베이스는 교실 데모에 이상적입니다.

---

CoreCoder는 코딩 어시스턴트가 종단 간 어떻게 작동하는지 보여주면서도 읽고, 수정하고, 확장할 수 있을 만큼 작은 완전한 기능의 테스트 적용(227개 테스트) 파이썬 패키지입니다.