Yulin-Bi/CodeAuto

현재 주류인 AI Coding 도구들은 거의 모두 TypeScript 또는 Python으로 구현되어 있으며, JVM 생태계는 심각하게 결여되어 있습니다.

Java를 주력 언어로 사용하는 개발자들에게 AI Coding Agent를 학습하거나 2차 개발하는 것은 종종 언어의 장벽을 넘어야 하기에 진입 장벽이 매우 높습니다.

CodeAuto는 Claude Code 소스 코드의 설계 아이디어를 참고하고 MINICODE의 경량화 및 확장 가능 개념을 융합하여, Java 21로 구축된 단순하고 확장 가능하며 JVM 개발자에게 친숙한 AI 프로그래밍 에이전트 런타임(Runtime)입니다.

일반 CLI와 전체 화면 TUI 두 가지 상호작용 방식을 제공하며, 도구 호출(Tool Calling), 권한 승인, 파일 diff 리뷰, 세션 저장 및 복구, 컨텍스트 압축, Skills, MCP, 지속성 메모리(Persistent Memory), 다단계 프로젝트 명령 로드, 자가 성찰(Reflexion) 및 ACE 구조화된 경험 메모리를 내장하고 있습니다.

• JDK 21
• Maven 3.9 이상 버전
• 추천 터미널: Windows Terminal / PowerShell, macOS Terminal, Linux 터미널

테스트 실행:

mvn test

API Key가 필요 없는 오프라인 Mock 모드로 TUI 시작:

mvn exec:java "-Dexec.args=--mock --tui"

실제 모델 모드로 TUI 시작:

mvn exec:java "-Dexec.args=--tui"

일반 CLI 모드:

mvn exec:java

Shaded JAR 빌드:

mvn package -DskipTests
java -jar target/codeauto-0.1.0-SNAPSHOT-shaded.jar --tui

또한 시작 스크립트를 사용하여 어느 디렉토리에서나 실행할 수 있으며, 자동으로 현재 디렉토리를 작업 디렉토리로 설정합니다:

bin/codeauto --tui
bin/codeauto.bat --tui

다른 디렉토리를 작업 디렉토리로 지정:

bin/codeauto --cwd /path/to/project --tui

bin 디렉토리를 PATH에 추가하면, 어느 디렉토리에서든 직접 호출할 수 있습니다:

codeauto --tui # 현재 디렉토리가 작업 디렉토리
codeauto --mock --tui # 오프라인 Mock 모드
codeauto --cwd D:/other-project # 다른 작업 디렉토리 지정

Windows PowerShell (관리자 권한)에서 PATH 추가:

[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\CodeAuto\bin", "User")

CodeAuto는 현재 Anthropic Messages API 어댑터와 오프라인 Mock 어댑터를 내장하고 있습니다.

설정 우선순위 (낮은 순에서 높은 순):

• 기본값 (Default)

• 환경 변수 (Environment Variables)

• 프로젝트 레벨
  .codeauto/settings.json

• 사용자 레벨
  ~/.codeauto/settings.json

• CLI 파라미터

PowerShell 예시:

$env:CODEAUTO_BASE_URL="https://api.anthropic.com"
$env:CODEAUTO_AUTH_TOKEN="your-api-key"
$env:CODEAUTO_MODEL="your-model-name"
...

macOS / Linux 예시:

export CODEAUTO_BASE_URL="https://api.anthropic.com"
export CODEAUTO_AUTH_TOKEN="your-api-key"
export CODEAUTO_MODEL="your-model-name"
...

사용자 레벨 설정 예시:

{
"baseUrl": "https://api.anthropic.com",
"authToken": "your-api-key",
...

TUI와 CLI에서 모델을 직접 전환하고 지속적으로 유지할 수 있습니다:

/model <name>

각 API마다 extended thinking (사고 블록) 처리 요구 사항이 다릅니다:

DeepSeek v4: extended thinking을 활성화할 때, thinking 블록을 그대로 API에 다시 전달해야 합니다. 그렇지 않으면 400 에러가 반환됩니다. stripThinking: false로 설정하십시오.

(기본값). Anthropic: extended thinking (확장 사고)이 활성화된 경우, thinking 블록을 API로 다시 전달할 수 없으므로 제거해야 합니다. stripThinking: true로 설정하십시오.

GLM / MiniMax: 현재 extended thinking이 활성화되지 않아 thinking 블록이 생성되지 않으므로, 두 설정 모두 영향이 없습니다.

설정 방식 (우선순위 높은 순):

# CLI 파라미터
codeauto --strip-thinking
# 환경 변수
...

• 일반 CLI 대화 모드

• JLine 3 풀스크린 TUI (Text User Interface)

• Header / Transcript / Prompt / Footer 패널

• Markdown의 ANSI 렌더링

• CJK (한중일) 표시 너비 및 중국어 입력 지원

• 마우스 휠, PageUp/PageDown, Alt/Ctrl 방향키 스크롤

• 슬래시(/) 메뉴, Tab 완성, 입력 히스토리

• 슬래시 메뉴 높이 제한 표시로 명령 프롬프트가 화면을 가득 채우는 것 방지

• 긴 텍스트의 자동 줄바꿈 우선 적용하여 좁은 창에서 행 끝이 ...로 잘리는 현상 감소

• Anthropic 텍스트 응답의 스트리밍 출력 지원: TUI는 제자리 새로고침, CLI는 수신과 동시에 출력

• 권한 승인 팝업 및 피드백과 함께 거부 (Deny with Feedback)

• 모델의 최종 응답 (final response), 진행 메시지 (progress message), 도구 호출 (tool call) 루프 지원

• 도구 결과 피드백 (tool result backfilling) 및 최대 단계 제한 지원

• 제공자별 토큰 사용량 (provider usage token) 통계 지원, 누락 시 로컬 추정치 사용

• 자동 컨텍스트 압축 및 미세 압축 지원

기본적으로 23개의 내장 도구가 등록되어 있습니다:

• 파일 관련:
  list_files
  , grep_files
  , read_file
  , write_file
  , edit_file
  , patch_file
  , modify_file

• 명령 및 상호작용:
  run_command
  , ask_user
  , background_tasks

• 네트워크:
  web_fetch
  , web_search

• 확장:
  load_skill

• 메모리:
  save_memory
  , list_memory
  , delete_memory

• 작업 (Task):
  todo_create
  , todo_update
  , todo_list

• MCP helper:
  list_mcp_resources
  , read_mcp_resource
  , list_mcp_prompts
  , get_mcp_prompt

TUI는 모델을 거치지 않고 직접 실행할 수 있는 로컬 단축 명령도 지원합니다:

/ls [path]
/grep <pattern>::[path]
/read <path>
...

세션은 워크스페이스 (workspace)별로 격리되며 다음 경로에 저장됩니다:

~/.codeauto/projects/

자주 사용하는 명령:

/sessions
/resume
/resume <id>
...

CLI 파라미터:

mvn exec:java "-Dexec.args=--resume"
mvn exec:java "-Dexec.args=--resume <id>"
mvn exec:java "-Dexec.args=--fork <id>"

CodeAuto는 세션 간 메모리를 지원하며, 기본적으로 다음 경로에 저장됩니다:

~/.codeauto/memory/

메모리는 frontmatter Markdown 파일로 저장되며, 유형은 다음과 같습니다:

user

feedback

project

reference

새 세션을 시작할 때 관련 메모리는 system prompt의 <system-reminder> 영역에 주입됩니다. 24시간 이상 업데이트되지 않은 메모리는 [stale]로 표시되어, 모델이 이를 의존하기 전에 먼저 확인하도록 유도합니다.

사용자 명령:

/memory list [query]
/memory add <type>::<title>::<content>
/memory delete <id>

메모리 저장은 AI에 의해 구동됩니다: system prompt는 사용자가 선호도, 프로젝트 약속, 아키텍처 결정 등을 표현할 때 AI가 능동적으로 save_memory를 호출하도록 안내합니다. 저장하기 전에 AI는 먼저 list_memory를 호출하여 모순되거나 오래된 기존 메모리가 있는지 확인하며, 있는 경우 delete_memory로 정리합니다. AI는 사용자에게 저장 위치를 묻습니다:

project: 현재 워크스페이스의 CLAUDE.md에 기록

global: ~/.claude/CLAUDE.md에 기록

codeauto

codeauto: ~/.codeauto/CLAUDE.md에 기록

store: ~/.codeauto/memory/에 기록

모델은 내장된 도구를 통해 메모리 (Memory)를 관리합니다:

save_memory destination=store|project|global|codeauto
list_memory
delete_memory

CodeAuto는 시스템 프롬프트 (System Prompt)를 구축할 때 다단계 Markdown 지침을 로드합니다:

~/.claude/CLAUDE.md

~/.codeauto/CLAUDE.md

<project>/CLAUDE.md

<project>/CLAUDE.local.md

뒤에 위치한 로컬 지침일수록 우선순위가 높습니다. CLAUDE.local.md는 저장소에 커밋하지 않을 개인적인 선호 사항을 두기에 적합합니다.

CodeAuto는 민감한 명령 및 파일 편집에 대해 권한 계층 (Permission Layer)을 적용합니다:

• 위험한 명령 탐지
• 파일 편집 전 Unified Diff 리뷰 생성
• allow once / always / turn
• deny once / always / with feedback
• 권한은 ~/.codeauto/permissions.json에 영구 저장

권한 상태 확인:

/permissions

권한 규칙은 정확한 일치 (Exact Match) 및 와일드카드 일치 (Wildcard Match)를 지원합니다. 예:

Bash(npm run *)
Bash(python scripts/*)
Bash(git push --force*)
...

기술 (Skills)은 프로젝트 레벨 디렉토리에서 발견되며, 사용자 레벨 관리 설정도 지원합니다. load_skill을 통해 로드되면, 해당 기술의 전체 지침이 현재 세션의 매 라운드 시스템 프롬프트 (System Prompt)에 주입되어 AI가 전체 세션 동안 기술 지침을 준수하도록 보장합니다.

.codeauto/skills # 프로젝트 레벨 skills 디렉토리
.claude/skills # 프로젝트 레벨 .claude skills 디렉토리
~/.codeauto/skills.json # 사용자 레벨 관리형 skills (skills add/remove CLI)

관리 명령:

mvn exec:java "-Dexec.args=skills list"
mvn exec:java "-Dexec.args=skills add my-skill /path/to/skill"
mvn exec:java "-Dexec.args=skills remove my-skill"

CodeAuto는 stdio MCP 및 Streamable HTTP MCP를 지원합니다. 시작 시 구성된 모든 MCP 서버를 자동으로 발견하여 도구 레지스트리 (Tool Registry)에 등록하며, 에이전트 루프 (Agent Loop)에서 수동 지정 없이 자동으로 호출할 수 있습니다.

MCP 설정은 다음 위치에 둘 수 있습니다:

~/.codeauto/mcp.json # 사용자 레벨 글로벌 설정
<project>/.mcp.json # 프로젝트 레벨 설정 (사용자 레벨의 동일한 이름의 server를 덮어쓰지 않음)

# stdio 방식 (가장 일반적임)
codeauto mcp add fs npx -- -y @modelcontextprotocol/server-filesystem /tmp
# HTTP 방식 (mcp.json을 수동 편집하여 url 필드 추가)

설정 예시 (~/.codeauto/mcp.json):

{
"local-node": {
"protocol": "auto",
...

codeauto mcp list
codeauto mcp add <name> <command> [args...] [--protocol auto|content-length|newline-json] [--env KEY=VALUE...]
codeauto mcp login <name> --token <bearer-token>
...

TOKEN은 MCP_BEARER_TOKEN 및 MCP_AUTH_TOKEN 환경 변수로 자동 주입되므로, env에 중복으로 설정할 필요가 없습니다.

TUI 내에서 MCP 상태 확인:

/mcp

stdio 프로토콜은 auto (기본값), content-length, newline-json을 지원합니다. auto는 먼저 content-length를 시도하고, 실패하면 newline-json으로 되돌아갑니다 (Fallback).

MCP 서버의 초기화가 느린 경우, 타임아웃 대기를 방지하기 위해 프로토콜을 명시적으로 지정하는 것을 권장합니다.

{
"fs": {
"protocol": "newline-json",
...

Windows 환경의 Java ProcessBuilder

.cmd 또는 .bat 파일을 직접 실행할 수 없습니다. CodeAuto는 .cmd 래퍼 스크립트(wrapper script)를 자동으로 감지하고 분석하여, 하위의 실제 실행 파일(예: node.exe)을 추출해 직접 호출하므로 사용자가 수동으로 처리할 필요가 없습니다.

npx, node, python 등의 명령어를 전체 경로 지정 없이 바로 사용할 수 있습니다. auto 모드에서 content-length 협상 타임아웃 대기를 방지하기 위해 protocol을 newline-json으로 명시적으로 지정하는 것을 권장합니다.

/help
/tools
/skills
...

src/main/java/com/codeauto/
background/ 백그라운드 작업
cli/ Picocli CLI
...

현재 테스트 결과:

Tests run: 111, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS

주요 커버리지:

• AgentLoop + 스트리밍 출력 (Streaming Output) + 중단 취소
• ToolRegistry 및 내장 도구 (매개변수 호환성 포함)
• SessionStore + 압축 경계 (Compression Boundary)
• 컨텍스트 (Context) 압축 + 미세 압축 + 압축 결과물 디스크 저장
• PermissionManager + 와일드카드 규칙
• MCP client/service
• MemoryManager + bullet 직렬화 왕복 (Serialization Round-trip)
• InstructionLoader + 다단계 지시어 로딩 + Skill 세션 주입 + ACE Playbook 주입
• TodoStore
• CLI 인코딩 및 워크스페이스 (Workspace) 분석
• TUI 이스케이프 시퀀스 (Escape Sequence) + diff 하이라이트
• ReflectionService + 4종 트리거 감지 + FEEDBACK 메모리 저장 + Bullet 자동 생성
• Curator + BulletDelta ADD/REMOVE/TAG/카운터/항목 필터링/내용 업데이트 + Jaccard 중복 제거

현재 PowerShell 세션에서 UTF-8 설정을 권장합니다:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

Windows / Maven exec 환경에서 중국어 입력이 모델에 의해 오해받는 문제가 여전히 발생할 경우, 다음과 같이 명시적으로 지정할 수 있습니다:

$env:CODEAUTO_CLI_CHARSET="GBK"

또는:

mvn exec:java "-Dexec.jvmArgs=-Dcodeauto.cli.charset=UTF-8"

CodeAuto는 CLI 엔트리포인트에 org.jline.terminal.disableDeprecatedProviderWarning=true를 기본적으로 설정해 두었으므로, 정상 작동 시 해당 경고가 더 이상 표시되지 않아야 합니다.

SGR 마우스(mouse)를 지원하는 터미널을 사용 중인지 확인하십시오. Windows 환경에서는 Windows Terminal + PowerShell 조합을 추천합니다.

~/.codeauto/projects/ 디렉토리에 쓰기 권한이 있는지 확인하십시오. 저장 실패 시 경고만 표시되며 현재 답변이 중단되지는 않습니다.

web_search는 기본적으로 API Key 없이 DuckDuckGo HTML 검색을 시도합니다. 네트워크 환경 문제로 기본 검색 페이지에 접속할 수 없거나 자체 검색 프록시를 연결하려는 경우 다음과 같이 설정할 수 있습니다:

$env:CODEAUTO_SEARCH_URL="https://example/search?q={query}"

• 모델의 확장 사고 (Extended Thinking) 스트리밍 출력을 지원하며, TUI 하단에 최신 3줄의 사고 내용이 실시간으로 표시됩니다 (연한 노란색 표시). CLI에서는 조용히 무시됩니다.
• 다양한 API의 thinking 블록 반환 요구사항에 대응하기 위해 stripThinking 설정 스위치를 추가했습니다 (Anthropic에서 extended thinking을 활성화할 때 이를 제거해야 하는 경우 true로 설정)

；DeepSeek v4의 경우 반드시 반환해야 함 → false로 설정

(기본값). - 설정 우선순위: CLI --strip-thinking > 환경 변수 CODEAUTO_STRIP_THINKING > settings.json의 stripThinking 필드. AnthropicModelAdapter는 요청을 생성할 때 stripThinking 설정에 따라 어시스턴트 (assistant) 메시지 내의 사고 (thinking) 블록을 자동으로 필터링하거나 유지합니다.

• 매 대화 라운드가 종료된 후 실패 신호(도구 오류 / 최대 단계 도달 / 사용자 취소 / 사용자 불만족)를 자동으로 감지하여, 모델의 반성 (reflection)을 트리거하고 FEEDBACK 기억 (memory)을 저장합니다. - 반성 구조에는 '무엇이 잘못되었는가 (What Went Wrong) / 근본 원인 (Root Cause) / 다르게 수행했어야 할 사항 (What Should Have Been Done Differently) / 재사용 가능한 교훈 (Reusable Lesson)'이 포함됩니다.
• 반성 과정에서 '재사용 가능한 교훈 (Reusable Lesson)'을 추출한 후 자동으로 ACE 불릿 (ACE Bullet)을 생성합니다 ([bullet:<id>] ID 및 helpful/harmful 카운터 포함).
• 큐레이터 결정론적 증분 엔진 (Curator deterministic incremental engine): BulletDelta의 추가/업데이트/태그/삭제를 지원하며, Jaccard 유사도(임계값 0.55)를 통한 중복 제거 및 섹션 범위 매칭을 수행합니다.
• 파일 분리: 반성 (reflections) → <project>/.codeauto/reflections/, 불릿 (bullets) → <project>/.codeauto/bullets/, 기억 (memories) → ~/.codeauto/memory/.
• InstructionLoader는 ACE 플레이북 (ACE Playbook, 최대 10개)을 독립적으로 주입하며, 불릿은 일반 기억 용량을 차지하지 않도록 단일 행의 압축된 인덱스 형태로 표시됩니다.
• 반성은 비동기적으로 실행되며 (CompletableFuture.runAsync + List.copyOf 방어적 복사 사용), 사용자 상호작용을 차단하지 않습니다. detectTrigger는 이번 라운드의 증분 메시지만 스캔하여 (turnStartIndex 제한), 과거의 오류가 반복적으로 트리거되는 것을 방지합니다. - 모델의 답변에서 불릿을 인용할 때 [bullet:<id>]를 표기하며, ReflectionService가 자동으로 불릿 태그를 파싱하고 카운터를 업데이트합니다.

McpClient는 Windows 환경에서 .cmd / .bat 래퍼 스크립트를 자동으로 감지하여, 하위 실행 파일(예: node.exe)을 파싱 및 추출하여 직접 호출합니다. - 사용자는 npx, node, python 등의 명령어를 사용하여 MCP 서버를 직접 구성할 수 있으며

。 - 요약 끝에 파일 경로가 자동으로 주입되어, AI가 요약 정보가 부족하다고 판단할 경우 스스로 read_file을 호출하여 참조할 수 있습니다. - 자동 압축 및 수동 /compact 명령이 모두 적용됩니다.

• 능동적 기억 자동 캡처 팝업을 제거하여, 기억 저장은 완전히 AI에 의해 구동됩니다.

• Memory behavior: 지침을 통해 system prompt (시스템 프롬프트)를 강화하여, AI가 저장하기 전에 모순되거나 오래된 기억이 있는지 먼저 확인하도록 합니다.

• load_skill 로드 후, skill (스킬) 명령어가 매 라운드 system prompt (시스템 프롬프트)에 주입되며 [loaded]로 표시됩니다. - Skill (스킬) 목록은 이름과 설명을 표시하여 list_skills 호출을 줄입니다.

• todo_create, todo_update, todo_list 도구가 새로 추가되었으며, TUI 헤더에 진행 상황이 표시됩니다.

Tests run: 111, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS

만약 주소가 {query}를 포함하고 있다면, 도구가 이를 URL 인코딩된 검색어로 대체합니다. 그렇지 않으면 자동으로 q=<query> 파라미터를 추가합니다.