yangshun/teenycode

TypeScript로 작성된 아주 작은 코드 편집 에이전트 (200 LOC) — OpenAI와 통신하며 작업 디렉토리의 파일을 읽고, 목록을 나열하고, 편집할 수 있는 최소한의, 해킹 가능한 CLI (Command Line Interface)입니다.

이 저장소는 Amp의 "How to Build an Agent"를 기반으로 제작되었으며, 최소한의 CLI 코딩 에이전트의 핵심 요소를 보여주기 위한 **교육적 목적 (educational purposes)**을 위해 만들어졌습니다.

• OpenAI를 호출하고 도구 호출 (tool calls)을 사용하는 채팅 기반 CLI
• 파일 도구:
  read_file (파일 읽기), list_files (파일 목록 나열), edit_file (단일, 고유한 교체 또는 새 파일 생성) - 추측하기보다 파일을 읽는 것을 선호하며, 요청을 충족하는 가장 작은 편집을 수행합니다.
• 최소한의 의존성 (dependencies)과 직접 수정할 수 있는 단순한 코드

참고

bash 도구는 위험할 수 있고 이 저장소가 교육용으로 의도되었기 때문에 포함되지 않았습니다. 필요하다면 직접 추가할 수 있습니다.

• Node.js 22+
• npm / Vite Plus
• OpenAI API 키

저장소를 클론(cloning)하지 않고 즉시 실행해 보세요 (본인의 OpenAI API 키가 필요합니다):

export OPENAI_API_KEY=sk-...
npx teenycode

또는 npx teenycode를 실행하는 디렉토리의 .env 파일에 OPENAI_API_KEY=sk-...를 넣으세요.

한 줄로 실행하고 싶다면:

OPENAI_API_KEY=sk-... npx teenycode

또는 저장소를 클론하여 소스에서 실행할 수 있습니다:

npm install
cp .env.example .env # 그 후 .env를 편집하여 OPENAI_API_KEY를 설정하세요
npm start

Chat with <model>과 같은 프롬프트가 나타나면 요청을 입력하세요. exit, quit, :q 또는 Ctrl-C로 종료할 수 있습니다.

OPENAI_API_KEY가 누락된 경우, CLI는 설정 안내를 출력하고 종료됩니다.

src/index.ts: 엔트리 포인트 (Entry point); OPENAI_API_KEY를 확인하고 에이전트를 시작합니다.
src/agent.ts: 채팅 루프 (Chat loop), 도구 라우팅 (tool routing) 및 메시지 상태 관리
src/tools.ts: Node fs API로 구현된 세 가지 내장 도구

에이전트는 함수/도구 호출 (function/tool calling) 기능이 있는 OpenAI Chat Completions를 사용합니다. 도구 입력은 Zod로 검증되며, 스키마는 모델을 위해 JSON Schema로 내보내집니다.

➜ teenycode git:(main) ✗ OPENAI_API_KEY=sk-... npx teenycode
Chat with gpt-5 (type 'exit' or 'quit' or use Ctrl-C to quit)
You: What is this repo about?
...

에이전트(Agent)는 세 가지 파일 도구(file tools)를 노출합니다:

read_file

(path: string

): 상대 경로(relative path)에 있는 파일의 텍text 내용을 읽고 반환합니다.

list_files

(path: string

): 주어진 경로의 파일과 디렉터리(directories)를 나열합니다 (현재 디렉터리의 경우 "."를 사용하세요).

edit_file

(path: string, old_str: string, new_str: string

): 주어진 파일에서 old_str과 정확히 일치하는 한 군데를 new_str로 교체합니다.

관례(Conventions):

• 모든 경로는 현재 작업 디렉터리(current working directory)를 기준으로 하는 상대 경로입니다.

• 에이전트는 추측하기보다 읽는 것을 선호하며, 가능한 한 가장 작은 변경을 만드는 것을 목표로 합니다.

• 편집(Edits)은 설계 단계부터 정밀하게(surgical) 이루어집니다. 작업 내용을 git에 유지하고 자주 커밋(commit)하세요.

• 에이전트는 현재 작업 디렉터리를 기준으로 동작합니다.

vp install
cp .env.example .env
# .env를 편집하고 API 키를 설정하세요
...

vp check
vp lint --fix
vp fmt
...

Amp의 'How to Build an Agent'에서 발췌되었습니다.