FirstCoder: 내부 작동 원리를 볼 수 있는 로컬 Python 코딩 에이전트

내부 작동 원리를 보이도록 구축된 로컬 Python 코딩 에이전트.

English · 简体中文

FirstCoder는 Textual TUI, 도구 호출(tool calling), 권한(permissions), 세션(sessions), 그리고 컨텍스트 압축(context compaction) 기능을 갖춘 실제 작동 가능한 로컬 코딩 에이전트입니다. 일상 업무에 유용하고 코드 학습이 쉽도록 설계되었습니다.

코딩 에이전트가 실제로 어떻게 작동하는지 이해하고 싶다면, FirstCoder는 내부 메커니즘을 블랙박스 뒤에 숨기지 않고 움직이는 부분을 보이게 유지합니다.

• 에이전트 루프(agent loop), 도구 호출, 권한, 세션 및 컨텍스트 처리를 학습할 수 있습니다.
• 명확한 모듈 경계를 가진 작은 Python 코드베이스를 기반으로 구축되었습니다.
• 작동 방식을 검사하면서 로컬 코딩 에이전트를 사용할 수 있습니다.

대부분의 코딩 에이전트 데모는 표면적인 부분만을 보여줍니다. 즉, 프롬프트가 입력되고 코드 변경 사항이 출력되는 방식입니다. FirstCoder는 그 사이의 메커니즘에 초점을 맞춥니다.

OpenCode와 같은 더 큰 프로젝트와 비교했을 때, FirstCoder는 의도적으로 범위가 작습니다.

목표는 더 큰 코딩 에이전트를 능가하는 기능을 갖추는 것이 아닙니다. 목표는 시스템을 사용하기에 충분히 현실적이면서도, 끝까지 읽고 각 하위 시스템이 왜 존재하는지 이해할 수 있을 만큼 작게 유지하는 것입니다.

이는 또한 FirstCoder를 깊이 연구하고, 자신의 워크플로우에 맞게 조정하며, 확장한 후 이력서나 포트폴리오로 만들 수 있는 실용적인 저장소로 만듭니다.

튜토리얼 중심이거나 가벼운 학습 레포지토리에 비해, FirstCoder는 작지만 테스트 가능한 엔지니어링 시스템에 더 가까이 머무르려고 노력합니다.

이 레포지토리는 다음을 원하는 사람들을 위해 구축되었습니다:

• 코딩 에이전트가 어떻게 조립되는지 연구하고 싶을 때
• 로컬 Python 구현을 수정하거나 확장하고 싶을 때
• 인터뷰에서 설명할 만큼 아키텍처를 잘 이해하고 싶을 때

상세한 서브시스템 설계는 이 README가 아닌 문서에 있습니다.

pipx로 설치하기

pipx install firstcoder

TUI 시작하기:

firstcoder

TUI를 열지 않고 메시지 하나 실행하기:

firstcoder --message "Summarize this repository in one paragraph"

라인 기반 인터랙티브 모드 사용하기:

firstcoder --interactive

• 로컬 Python 코딩 에이전트
• 에이전트 활동을 숨기지 않고 노출하는 Textual TUI
• 직접적인 파일 변경 전에 하이라이트된 diff를 사용한 도구 호출(Tool calling)
• 세션 지속성, 재개 흐름 및 컨텍스트 압축
• 학습과 수정을 위한 스킬(Skills), 프로바이더 어댑터(provider adapters), 그리고 깔끔한 모듈들

시작자 설정 구성 만들기:

firstcoder config init
firstcoder config path
firstcoder config show

비밀 정보는 환경 변수에 보관하기:

export FIRSTCODER_API_KEY="your-api-key"

기본 설정 위치:

global: ~/.config/firstcoder/config.toml
project: ./firstcoder.toml

프로바이더 지원은 OpenAI Chat Completions와 호환되는 경로와 네이티브 Anthropic Messages API 어댑터에 중점을 둡니다. 두 경로 모두 동일한 내부 완료/스트리밍 계약(텍스트 델타, 도구 호출 누적, 강제 tool_choice, 사용량, 그리고 PROMPT_TOO_LONG)을 구현합니다.

-style 오류 분류). TUI의 네이티브 멀티모달 입력은 붙여넣기된 파일 경로와 클립보드 이미지를 스테이징할 수 있으며, 이미지나 작은 텍스트 파일은 비전(vision)을 지원하는 프로바이더로 세션/컨텍스트 파이프라인을 통해 전송됩니다. 모델과 프로바이더의 비전 기능 여부가 여전히 중요합니다. Anthropic에서만 제공되는 프롬프트 캐싱 같은 추가 기능들은 선택적인 미래 작업으로 남아 있습니다. FirstCoder는 아직 OpenAI Responses API를 사용하지 않습니다.

하나의 글로벌 또는 프로젝트 TOML 파일에 여러 프로바이더/모델 프로필을 유지할 수 있습니다. 프로젝트 값은 글로벌 값을 덮어쓰므로, 프로젝트는 필요한 필드만 재정의할 수 있습니다:

default_model = "yuren/gpt-5.6-terra"
task_boundary_classifier_model = "yuren/gpt-5.6-luna"
[providers.yuren]
...

firstcoder --model provider/model을 사용하여 실행에 대한 초기 프로필을 선택합니다. TUI에서는 /models를 입력하면 구성된 모델 피커가 열리고, /model provider/model을 입력하면 즉시 전환됩니다. firstcoder config show는 구성된 모델 참조와 레이블을 출력하지만, API 키, 환경 변수 값, 요청 본문(request bodies), 또는 모델 상태 내용은 절대 출력하지 않습니다.

temperature, max_tokens, 그리고 extra_body는 메인 모델 요청과 함께 전송됩니다. reasoning_effort는 요청 확장(request extension)으로 표현되며 선택된 프로바이더가 이를 지원할 때 전달됩니다. 이를 인식하지 못하는 프로바이더는 거부하거나 무시할 수 있습니다. 내부 분류기(Internal classifiers)와 압축 요약(compact summarization)은 자체적인 제한된 토큰 예산(bounded token budgets)을 유지합니다.

task_boundary_classifier_model은 선택 사항입니다. 설정된 경우, 숨겨진 작업 경계 요청(hidden task-boundary requests)은 해당 고정 모델 프로필을 사용하며, 메인 에이전트와 L4 압축(L4 compaction)은 계속해서 선택된 메인 프로필을 사용합니다. 이는 동일한 프로바이더의 다른 모델을 가리킬 수 있으므로, 해당 프로바이더의 API 키 환경 변수와 기본 URL을 재사용합니다. 이 모델의 temperature와 요청 확장은 상속되지만, 출력은 512 토큰으로 제한됩니다. 프로바이더/형식 오류는 여전히 기존의 보수적인 uncertain 결정으로 폴백(fall back)합니다.

세심한 사용자들을 위한 작은 정보: 일부 제공업체/모델 조합은 TUI 상단 바에 약간 더 많은 특징을 부여합니다.

FirstCoder의 TUI는 에이전트 루프를 숨기는 대신 노출하도록 설계되었습니다. 세션 상태, 스트리밍되는 어시스턴트 출력, 도구 호출(tool calls), 도구 결과(tool results), 그리고 권한 프롬프트(permission prompts)를 한 곳에서 확인할 수 있습니다.

로컬 파일을 write, edit, apply_patch, 또는 delete 변경하기 전에, FirstCoder는 빨간색 삭제 항목, 녹색 추가 항목, 파일별 통계 및 제한된 확장 제어 기능을 갖춘 신뢰할 수 있는 통합 diff를 생성합니다. 표준 모드에서는 일반적인 권한 확인을 동반하며, 기존 부여(grant) 또는 공격적 모드(aggressive mode)에서도 검토 전용 적용(review-only Apply) 확인이 필요합니다. 검토된 작업을 승인하거나 거부하거나 reject: <피드백>으로 응답하여 모델이 제안된 변경 사항을 수정할 수 있도록 합니다. FirstCoder는 디스패치 직전에 검토된 파일 스냅샷을 재확인하고, 동시 변경으로 인한 우발적인 덮어쓰기를 줄이기 위해 오래된(stale) 작업을 차단합니다. 이는 파일 시스템 수준의 원자적 트랜잭션이 아닌 보호 장치입니다. 바이패스 모드에서는 검토가 비차단 이벤트로 표시되고 작업이 즉시 진행됩니다. Harbor 어댑터는 비대화형 작업 턴을 위해 해당 이벤트를 비활성화합니다. 임의의 명령어 효과는 안전하게 사전 계산될 수 없기 때문에, 셸 명령어는 활성 모드의 권한 정책을 따릅니다.

준비 상태(Ready state):

대화 흐름(Conversation flow):

• 기술 문서 색인(Technical Docs Index)
• 중국어 문서 색인(Chinese Docs Index)
• 아키텍처(Architecture)
• 코드베이스 읽기 가이드(Codebase Reading Guide)
• 멀티모달 입력 디자인(Multimodal Input Design)
• MCP 클라이언트 구성(MCP Client Configuration)
• Harbor 평가(Harbor Evaluation)

개발 의존성 설치(Install dev dependencies):

python -m venv .venv
.venv/bin/python -m pip install -e ".["dev]"

모든 테스트 실행(Run all tests):
.venv/bin/python -m pytest

집중 테스트 파일 실행(Run a focused test file):
.venv/bin/python -m pytest tests/test_app_tui.py -q

FirstCoder는 대부분의 코딩 에이전트가 다루지 않는 질문에 답하기 위해 구축되었습니다:

에이전트가 스트리밍하고, 도구를 호출하고, 권한을 요청하고, 컨텍스트를 압축하며, 세션을 재개할 때 내부적으로 실제로 무슨 일이 일어나는가?

이는 실제로 실행 가능한 에이전트이지만, 한 서브시스템씩 학습할 수 있는 읽기 쉬운 Python 프로젝트이기도 합니다.