자체 학습 AI Agent 명령줄 도구 - 인터랙티브 경험은 claude code에 대응하며, Windows 우선, 즉시 사용 가능

CodeAgent는 터미널에서 실행되는 AI 코딩 비서입니다. 자연어로 지시하면 코드 읽기, 파일 수정, 명령어 실행, 자료 검색 등 모든 작업을 처리합니다. 이 도구는 자체적인 '능력 습득' 메커니즘을 가지고 있어 대화 기록에서 재사용 가능한 기술을 축적하며 사용할수록 더욱 능숙해집니다.

단순한 껍데기나 번역이 아닙니다. 인터페이스부터 Agent의 주 루프까지 한 줄 한 줄 수작업으로 구현된 완전한 코드이며, 주석은 모두 중국어로 되어 있습니다:

• 📚
  Agent 개발을 배우고 싶다면, 이것이 실습 교재입니다. 도구 자동 등록, 컨텍스트 계층 압축, 권한 승인, 서브 에이전트 팀, 워크플로우 엔진, 메모리 시스템 등 실제 구동 가능한 Agent의 전 과정(full link)이 여기에 담겨 있습니다. 각 모듈은 '쉬운 설명 흐름 → 매개변수 → 반환' 형식의 상세한 중국어 주석을 가지고 있어 코드를 읽는 것이 튜토리얼을 보는 것 같습니다. - 🛠
  직접 수정해 보세요. 불편한 점이 있다면 fork하여 바로 수정할 수 있습니다. 코드 구조가 명확하고 주석도 충분해서 수정하는 데 어려움이 없습니다. PR(Pull Request) 환영: 버그 수정, 기능 추가, 인터페이스 최적화 모두 가능합니다. - 💬
  질문은 커뮤니티에 문의하세요. 막히거나 이해가 안 되거나 디자인을 논의하고 싶다면 Issues나 Discussions에 게시글을 올리면 반드시 답변이 있습니다.

터미널 경험 (claude code 대응)

• 스트리밍 응답 둥근 모서리 상자, 사고 흐름 어두운 상자, 도구 이벤트 줄(● Bash(...) + ⎿ 결과) - 위험 명령어 / 화이트리스트 외 파일의 승인 패널: '한 번 허용' / '항상 허용' / '거부' 세 가지 선택이 가능하며, 답변 후 자동으로 사라져 컨텍스트를 오염시키지 않습니다. - Ctrl+C 의미 분리: 대화 중 일시 중단(interrupt), 더블 클릭 강제 종료; 승인 패널에서 Ctrl+C는 취소 및 전체 라운드 중단
• 스킨 시스템, 푸터 상태 표시줄, 명령어 자동 완성, 입력 기록, 긴 텍스트 붙여넣기 시 자동 참조 처리

모델과 도구 (Model & Tool)

• 다중 모델 연결: OpenAI 호환 프로토콜(기본 DeepSeek) 및 Anthropic 프로토콜 모두 설정 가능; 주 모델 + 보조 소형 모델(압축/검색/메모리 추출 등 잡무는 저렴한 모델 사용)
• 도구 자동 등록 시스템:
  tools/
  아래 모듈을 import하면 자동으로 등록되며, '패키지'(toolset) 단위로 모델에 전달할 도구 세트를 제어합니다. - MCP 외부 도구: 프로젝트 레벨의 .mcp.json에 선언만 하면 연결되고, 최초 연결 시 승인이 필요합니다. - 내장 도구는 파일 읽기/쓰기, 터미널 실행, 검색, 코드 검색, 웹 크롤링, 백그라운드 작업, 서브 에이전트 할당 등을 포괄합니다.

보안 방어선 (Security)

• 파괴적 명령어 승인 + 세션 간 화이트리스트(명령별 / 접두사 규칙으로 기억) - 주입면 감지($() 등, 프로세스 대체 등의 '보이는 것이 실행되는 것'이 아닌 형태에 대한 승인), 삭제 경로 레드라인, 자가 보호 기능 - 키 스캔(API key를 파일/메모리에 쓰지 못하게 방지), SSRF 방어, 웹 콘텐츠 주입 격리
• Linux 환경에서 선택적 bwrap 격리 실행

메모리와 자체 학습 (Memory & Self-Learning)

• 장기 메모리: MEMORY.md에 인덱싱 + JSONL 저장 + 검색 결과를 임시로 주입(정식 히스토리에 오염되지 않음) - 스킬 시스템: 사용자 스킬 + 플러그인 마켓 스킬(/plugin) 관리, 접촉 파일 경로 조건에 따라 활성화 가능 - 자체 학습 파이프라인: 대화 기록을 관찰 → 새로운 기술 축적(발견적/보조 모델 두 가지 관찰 방식)

협업과 자동화 (Collaboration & Automation)

• 서브 에이전트: 동기식 / 백그라운드 할당, worktree 격리, 백그라운드 에이전트가 승인받지 못하면 자동으로 fail-closed 처리 - 팀 모드: coordinator / worker / 메시지 버스 / 이메일 - 워크플로우 엔진: 결정론적 오케스트레이션, 로그 중단 지점 재개, 비용 상한 설정
• 예약 작업(cron), 선언적 훅(hooks), 작업 목록, 세션 체크포인트 되돌리기(/rewind)

컨텍스트 엔지니어링 (Context Engineering)

• 계층 압축: L1 경량 자르기 → L4 심층 요약, 배치 간 도구 요약, 시간 기준 구 결과 정리 - 접두사 캐시 친화적: 임시 메시지 주입 및 제거 시점을 세심하게 다루어 캐시 접두사를 손상시키지 않음

전제 조건: Python 3.11+ 및 uv(Python 패키지 관리자) 필요.

# 1) uv 설치 (이미 있다면 건너뛰기)
# Windows (PowerShell): powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
...

팁: 모델 변경 / 제조사 변경은 세션에서 /model을 입력하여 안내에 따라 설정하거나, ~/.codeAgent/settings.json 파일을 직접 편집하세요.

세션 내 40개 이상의 슬래시 명령어 중 자주 사용되는 것은 다음과 같습니다:

런타임 데이터는 ~/.codeAgent/에 통합 저장됩니다.

(환경 변수 CODEAGENT_HOME으로 덮어쓰기 가능, 테스트 및 다중 설정 격리용):

호출 체인은 한 문장으로 요약: main.py
(점화: 콘솔 코딩, 터미널 부트스트랩) → cli.main
→ run_interactive
(REPL + 슬래시 명령어 + RuntimeContext 조립) → AIAgent.run_conversation
(메인 루프 핵심).

메인 루프 매 라운드: 메시지 구성 (백그라운드 / 주기적 / 팀 / 계획 등 임시 메시지 주입) → 컨텍스트 압축 → 도구 세트 새로고침 → LLM 호출 → 도구 호출 분배, 모델이 더 이상 도구가 필요하지 않으면 종료.

uv run python scripts/verify.py # 60개 이상 회귀 검사 (코드 수정 후 먼저 실행)
uv run ruff check . # lint

어떤 터미널을 지원하나요? cmd / Windows Terminal / PowerShell에서 바로 사용 가능합니다. git-bash(mintty)에서는 자동으로 winpty를 사용하여 다시 시작되므로 수동 처리가 필요 없습니다. Linux / macOS도 지원하나요? Windows 우선 개발 및 검증되었습니다. Linux는 실행 가능하며 (bwrap 샌드박스 지원 포함), macOS는 이론적으로 사용 가능하지만 충분히 검증되지 않았습니다. 모델은 반드시 DeepSeek을 사용해야 하나요? 아닙니다. OpenAI 호환 엔드포인트 또는 Anthropic 프로토콜 엔드포인트라면 모두 가능하며, /model 또는 settings.json을 수정하여 변경할 수 있습니다. key는 환경 변수와 설정 파일 두 가지 방식으로 지원됩니다. 세션 데이터는 어디에 있나요? 전부 ~/.codeAgent/에 있으며, 이 디렉토리를 삭제하면 완전히 초기화됩니다.

MIT © 2026 Harvil1