AX-Copilot-Codex/README.md

AX Commander

Windows 전용 시맨틱 런처 & 워크스페이스 매니저

Alfred (macOS)에서 영감을 받아 Windows 환경에 최적화된 키보드 중심 생산성 도구입니다.

개발 참고: Claw Code 동등성 작업 추적 문서
docs/claw-code-parity-plan.md

---

주요 기능 (프리픽스 치트시트)

프리픽스	기능	예시
(없음)	앱·파일 퍼지 검색 + 앱 단축키	vscode, 크롬, ㅅㄷ (초성)
=	계산기 — 수식 즉시 계산, Enter로 결과 복사	= sqrt(16), = 2^10, = sin(30)
/	시스템 명령 — 잠금·절전·재시작·종료	/lock, /sleep, /shutdown
;	텍스트 스니펫 — 키워드로 저장된 텍스트 붙여넣기	;addr, ;sig
#	클립보드 히스토리 — 복사 이력 검색 & 재사용	# hello, #
@	URL 단축키	@gh → GitHub 열기
~	폴더 단축키	~dl → Downloads 폴더
>	명령 실행 / 배치 단축키	>git status
$	클립보드 텍스트 변환 (12종)	$json, $b64e, $upper, $ts
!	워크스페이스 저장·복원	!save work, !restore work

Alfred 대비 기능 현황

기능	Alfred	AX Commander
앱 퍼지 검색	✅	✅
한국어 초성 검색	❌	✅
파일 검색	✅	✅ (exe/lnk/bat/ps1)
계산기	✅	✅ = 프리픽스
시스템 명령	✅	✅ / 프리픽스 (7가지)
텍스트 스니펫	✅	✅ ; 프리픽스 + 변수 치환
클립보드 히스토리	✅	✅ # 프리픽스
클립보드 변환	❌	✅ $ 프리픽스 (12종)
URL 단축키	✅	✅ @ 프리픽스
폴더 단축키	✅	✅ ~ 프리픽스
터미널 명령	✅	✅ > 프리픽스
워크스페이스 관리	❌	✅ ! 프리픽스
플러그인 SDK	✅	✅ (IActionHandler)
HTTP API 스킬	✅	✅ (.skill.json)
테마 커스터마이징	❌	✅ (7종 프리셋 + 완전 커스텀)
설정 UI	✅	✅ (7탭 전체 GUI 설정)

---

설치 및 빌드

요구 사항

• OS: Windows 10 20H2 이상 (Windows 11 권장)
• .NET: 8.0 Runtime (Self-contained 빌드 시 불필요)

빌드

# 소스 클론
git clone https://github.com/your/oledic.git
cd "oledic/AX Commander"

# 개발 실행
dotnet run --project src/AxCommander

# Release 단일 파일 빌드 (self-contained)
dotnet publish src/AxCommander -c Release -r win-x64 --self-contained

릴리즈 게이트 실행

릴리즈 전에는 아래 스크립트로 빌드/패리티/리플레이/전체 테스트를 일괄 검증합니다.

powershell -ExecutionPolicy Bypass -File .\scripts\release-gate.ps1

빠른 점검만 필요할 때는 전체 테스트를 생략할 수 있습니다.

powershell -ExecutionPolicy Bypass -File .\scripts\release-gate.ps1 -SkipFullTest

데이터 경로

용도	경로
설정 파일	%APPDATA%\AxCommander\settings.json
로그	%APPDATA%\AxCommander\logs\app-YYYY-MM-DD.log
스킬 파일	%APPDATA%\AxCommander\skills\*.skill.json
크래시 덤프	%APPDATA%\AxCommander\crashes\

---

사용법

키보드 단축키

동작	단축키
런처 열기 / 닫기	Alt+Space
설정 열기	Ctrl+,
다음 항목 선택	↓
이전 항목 선택	↑
실행	Enter
자동완성 (선택 항목 제목 채우기)	Tab
닫기	Esc

계산기 예시

= 1 + 2 * 3          → 7
= sqrt(144)          → 12
= 2^10               → 1024
= sin(30)            → 0.5     (도 단위)
= log(1000)          → 3
= pi * 5^2           → 78.5398...
= 0xFF + 16          → 271
= round(3.14159, 2)  → 3.14

스니펫 변수

스니펫 내용에서 아래 변수를 사용할 수 있습니다:

변수	치환 값	예시
{date}	오늘 날짜	2026-03-23
{time}	현재 시각	14:30:00
{datetime}	날짜+시각	2026-03-23 14:30:00
{year}	연도	2026
{month}	월 (2자리)	03
{day}	일 (2자리)	23

---

플러그인 개발

DLL 플러그인

AxCommander.SDK를 참조하여 IActionHandler 인터페이스를 구현합니다.

using AxCommander.SDK;

public class MyHandler : IActionHandler
{
    public string? Prefix => "?";   // 트리거 프리픽스 (null이면 prefix 없는 핸들러)
    public PluginMetadata Metadata => new("MyPlugin", "설명", Version: "1.0");

    public async Task<IEnumerable<LauncherItem>> GetItemsAsync(string query, CancellationToken ct)
    {
        return [ new LauncherItem("제목", "부제목", null, myData, Symbol: "\uE721") ];
    }

    public Task ExecuteAsync(LauncherItem item, CancellationToken ct)
    {
        // item.Data로 전달한 데이터를 꺼내 실행 로직 작성
        return Task.CompletedTask;
    }
}

빌드한 DLL 경로를 settings.json의 plugins 배열에 추가:

{
  "plugins": [
    { "path": "C:\\MyPlugins\\MyPlugin.dll", "enabled": true }
  ]
}

JSON 스킬 (코드 없이 HTTP API 연동)

%APPDATA%\AxCommander\skills\ 에 .skill.json 파일을 놓으면 됩니다.

{
  "id": "github-search",
  "name": "GitHub 검색",
  "prefix": "@gh",
  "credential": { "type": "bearer_token", "credentialKey": "github_token" },
  "request": {
    "method": "GET",
    "url": "https://api.github.com/search/repositories?q={{INPUT}}&per_page=10"
  },
  "response": {
    "resultsPath": "items",
    "titleField": "full_name",
    "subtitleField": "description",
    "actionUrl": "html_url"
  },
  "cache": 30
}

---

테마

7가지 내장 테마와 완전 커스텀 테마를 지원합니다.

테마	특징
system	Windows 다크/라이트 모드 자동 감지
dark	딥 네이비 다크 (기본)
light	클린 화이트 라이트
oled	순수 블랙 (OLED 절전)
nord	Arctic 컬러 팔레트
monokai	Sublime Text 스타일
catppuccin	Mocha 따뜻한 파스텔
sepia	황갈색 아날로그 감성
custom	14개 색상 완전 커스터마이징

설정 UI(Ctrl+, → 테마 탭)에서 클릭 한 번으로 즉시 미리보기 적용.

---

변경 이력

v0.7.3 — AX Agent 권한 코어 재구성 + 입력 계층 정리

업데이트: 2026-04-04 16:24 (KST)

분류	내용
권한 코어 재구성	Default → AcceptEdits → Plan → BypassPermissions → DontAsk → Deny 체계로 정규화하고, 기존 Ask/Auto 값은 호환 alias로 유지
규칙 해석 순서 정리	권한 판정을 deny 규칙 → allow/override 규칙 → 글로벌 모드 → 기본 Ask 순서로 재구성
도구 권한 클래스 분리	file_write/file_edit/file_manage와 process/build_run/test_loop/snippet_runner/spawn_agent 계열을 분리해 AcceptEdits와 Plan의 실제 동작 차이를 반영
AX Agent 권한 UI 반영	권한 팝업, 상단 배너, slash 명령 결과가 새 권한 모드 의미를 표시하도록 정리
AX Agent 설정창 복구	AgentSettingsWindow의 깨진 한글 문자열을 정리하고 운영 모드, 계획 모드, 추론 강도, 폴더 데이터 활용 라벨을 현재 AX 표현 체계로 복구
권한 용어 통일	권한 팝업과 인라인 설정에서 계획 중심, 완전 자동, 질문 없이 진행 등 한국어 표기를 일관되게 사용하도록 정리
권한 UI·로직 결합 정리	claw-code 권한 팝업 흐름에 맞춰 코어 4개(권한 요청/편집 자동 승인/계획 모드/권한 건너뛰기)를 기본 선택 순서로 정렬하고, 토글 순환도 동일 축으로 단순화
슬래시 팔레트 단순화	/ 팝업의 기본 선택을 첫 항목으로 바꾸고, 즐겨찾기 버튼/배지 UI를 제거해 아이콘+명령+설명 중심의 단순 리스트 탐색으로 정리
컴포저 패널 축소	하단 인라인 설정을 Fast/추론/계획/권한 중심으로 축소하고, 스킬/브라우저/MCP 버튼은 숨겨 입력 중심 UX로 정리
모델/프리셋 바 컴팩트화	입력창 상단 바를 더 촘촘한 크기로 정리하고, 긴 모델명은 자동 말줄임 처리해 레이아웃이 흔들리지 않도록 보강
좌측 패널 타이포 정돈	사이드바 헤더/메뉴/대화 리스트의 폰트 크기와 여백을 줄여 밀도를 맞추고, 대화 카드 제목·시간·상태 배지의 크기를 통일해 시인성을 개선
메시지 버블 정돈	사용자/어시스턴트 버블의 여백·폰트·타임스탬프·액션 버튼 크기를 줄이고 좌우 마진을 대칭화해 대화 로그 가독성과 정렬감을 개선
에이전트 이벤트 표시방식 정리	실행 배너의 과도한 펼침 UI를 제거하고 요약 길이를 제한해 한눈에 상태를 읽도록 단순화, 권한/계획/실행 라벨을 한국어 기준으로 통일
도구 결과 카드 단순화	파일 경로 배너를 파일명 + 디렉터리 2단 구조로 정리하고, 빠른 작업 버튼을 아이콘 전용(프리뷰/열기/폴더/복사)으로 축소해 시각적 복잡도를 낮춤
작업 요약 팝업 정돈	팝업 헤더/필터 밀도를 낮추고 전체·권한·대기·도구·서브·훅 중심으로 재정렬해 스크롤 시 탐색 피로를 줄임
권한 이력 카드 재구성	권한 카드/이력을 현재 모드·설명·기본/예외 + 시간·도구·결과 구조로 단순화하고, 권한 액션 버튼도 최신 용어(활용하지 않음/권한 요청/편집 자동 승인/계획 모드/권한 건너뛰기)로 통일
최근 실행 카드 압축	최근 에이전트 실행 카드에서 상세 로그/파일 나열과 분기 액션을 줄이고 요약+카운트+타임라인 중심으로 정리해 표시 밀도와 스캔 속도를 개선
작업 카드 버튼 스타일 통일	작업 요약/권한/훅/백그라운드 카드 버튼을 공통 생성 함수로 통일해 패딩·폰트·테두리·색상 톤을 일관화하고 카드 간 버튼 밀도 차이를 제거
카드 타이포 계층 정렬	작업/훅/백그라운드 카드의 제목·본문 글자 크기와 굵기를 통일하고 PrimaryText/SecondaryText 기반으로 대비를 맞춰 카드 간 시각 리듬을 정리
카드 아이콘 규칙 통일	작업 종류별 아이콘/색을 공통 매핑으로 통일하고, 작업·훅·백그라운드 카드 헤더에 아이콘을 배치해 상태 인지가 한눈에 되도록 정리
권한 팝업 선택 강조 개선	권한 모드 리스트에서 활성 항목에 배경/테두리/체크 아이콘을 적용하고 설명 줄간격·아이콘 정렬을 조정해 선택 상태와 읽기 흐름을 명확화
권한 예외/거부 영역 압축	권한 팝업의 도구별 예외와 최근 권한 거부 블록을 아이콘 헤더+간결 라벨 체계로 정리하고 버튼 명칭을 권한 용어(권한 요청/편집 자동 승인/활용하지 않음/예외 해제)로 통일
권한 팝업 섹션 접힘/펼침	기본 화면은 핵심 권한 모드만 노출하고 현재 권한 요약/도구별 예외/최근 권한 거부/고급 모드는 접힘 섹션으로 전환해 codex/claude식 간결 흐름으로 정리
권한 팝업 섹션 상태 기억	접힘 섹션의 마지막 펼침 상태를 settings.dat에 저장해 팝업 재오픈 시 사용자 마지막 선택을 복원
슬래시 팔레트 그룹 상태 기억	/ 팔레트에 명령/스킬 접힘 헤더를 추가하고 마지막 펼침 상태를 저장해 재오픈 시 복원, Up/Down 이동도 펼쳐진 그룹 항목만 순회하도록 보정
슬래시 최근 사용 상단 고정	/ 팔레트의 명령/스킬 그룹 내부 항목을 최근 사용(MRU) 기준으로 상단 정렬하고 최근 배지를 표시, 선택 스크롤도 실제 렌더 항목 기준으로 정확히 보정
슬래시 핀 고정 결합	/ 팔레트 항목 우측에 핀 토글을 추가하고 정렬 우선순위를 핀 > 최근 > 이름으로 적용해 자주 쓰는 명령을 고정 유지
AX Agent 기본 활성화	ai_enabled 기본값을 활성화로 변경하고 설정 로드 정규화 단계에서 비활성 값이 들어와도 자동으로 활성화되도록 보정
업데이트 안내 메시지 제거	앱 시작 시 설정 마이그레이션 후 표시되던 설정 업데이트 메시지박스를 제거해 업데이트 설치 직후 팝업 노출을 중단
슬래시 핀/최근 개수 설정 연동	AX Agent 설정창에서 슬래시 핀 최대 개수, 슬래시 최근 최대 개수를 조절할 수 있도록 추가하고 런타임(MRU/핀 정렬) 제한에 즉시 반영
슬래시 개수 설정 QA 완료	핀/최근 상한 적용 후 / 팔레트 정렬과 실행 경로를 회귀 점검하고 ChatWindowSlashPolicyTests 39개를 통과하여 동작 안정성을 확인
슬래시 퀵관리/권한 키보드 보강	/ 팔레트 헤더에 정리/전체 접기·펼치기를 추가하고, 권한 팝업에 Tab/Enter/Esc 중심 키보드 조작(항목 선택·섹션 토글·닫기)을 보강
슬래시/권한 접근성 완성도 보강	/ 팔레트에 모두 접힘 안내와 섹션 상태 라벨을 추가하고, 권한 팝업 오픈 시 첫 포커스 이동/Enter·Space 선택/ESC 닫기를 보강해 키보드 사용성을 개선
설정 즉시 반영 가시성 보강	AX Agent 설정의 슬래시 핀/최근 상한 항목에 저장 후 즉시 반영 안내를 추가해 조작 결과를 명확히 인지하도록 정리
회귀 패키지 통과	전체 테스트 436개 통과로 슬래시/권한/설정 저장 경로 변경 후 회귀 안정성 확보
슬래시 탐색 입력 확장	/ 팝업에서 휠/방향키 외에 PageUp/PageDown/Home/End 이동을 추가하고 고해상도 휠 델타를 단계 이동으로 보정해 스크롤 사용성을 개선
모델 빠른설정 단일 라인 강화	입력창 상단 모델 버튼을 AX Agent 내부 빠른 설정 토글로 전환하고, 모델/프리셋 버튼 높이와 패딩을 정돈해 Codex/Claude형 단일 라인 흐름에 맞춤
UI 점검 체크리스트 추가	내부/사외 모드 포함 UI 회귀 점검 문서를 docs/UI_UX_CHECKLIST.md로 추가해 시나리오 기반 검증 기준을 명문화
권한 모드 표면 통일	권한 표시 명칭을 활용하지 않음/소극 활용/적극 활용/계획 중심/완전 자동/질문 없이 진행으로 통일하고 팝업 선택 순서를 동일 체계로 재정렬
권한 기본 동작/순환 보강	Chat 탭 기본 권한을 활용하지 않음으로 적용하고, /sandbox-toggle 및 AX Agent 설정 권한 순환을 같은 순서(활용하지 않음→소극→적극→계획→완전 자동→질문 없이 진행)로 맞춤
운영 모드 회귀 점검 강화	OperationModePolicyTests, OperationModeReadinessTests, LlmOperationModeTests 필터 테스트(18건)를 통과해 internal/external 차단·허용 경로를 재검증
권한 팝업 밀도 재정돈	권한 섹션 헤더/카드/행의 패딩·폰트·줄간격을 조정해 과밀 영역을 완화하고 Codex/Claude형 스캔 속도에 맞춤
좌측/컴포저 라벨 정리	좌측 기본 카테고리 라벨을 주제 선택/작업 선택으로 통일하고, 입력 상단 바 패딩·간격을 미세 조정해 단일 라인 정돈 강화
체크리스트 실행 결과 기록	docs/UI_UX_CHECKLIST.md에 2026-04-04 12:22 기준 점검 결과(운영모드 필터 18건 + 전체 436건 통과)를 기록
권한 상태 표시 간소화	권한 상태 텍스트(/permissions, /allowed-tools)를 운영 모드 포함 축약형으로 정리하고 권한 버튼 툴팁에 동일 정보를 반영
설정창 외부 진입 안정화	AX Agent 설정창 오픈 시 리소스 병합 실패를 방어하고, 외부 진입 경로를 Dispatcher 기반으로 안정화
모델 라벨 반응형 보강	컴포저 상단 모델 라벨에 말줄임(MaxWidth + CharacterEllipsis)을 적용해 좁은 폭에서 레이아웃 깨짐을 방지
슬래시 탐색 순서 정합화	/ 팝업의 방향키/휠/Home/End 이동 기준을 렌더 순서(핀/최근 정렬 적용 순서)로 통일해 스크롤·선택 체감 불일치를 해소
권한 요청창 한국어/인코딩 복구	PermissionRequestWindow의 깨진 문자열을 복구하고 권한 선택/위험도/미리보기 문구를 한국어 기준으로 정리
slash 명령 카탈로그 분리	ChatWindow 내부 대형 slash 사전을 SlashCommandCatalog로 분리해 입력 계층 결합도를 낮추고 유지보수 범위를 축소
slash 조회 API 전환	내장 slash 매칭/조회 경로를 SlashCommandCatalog.MatchBuiltinCommands/TryGetEntry로 통일
권한 표시 카탈로그 분리	권한 모드 라벨/설명/아이콘/색을 PermissionModePresentationCatalog로 분리해 팝업 표면 기준을 단일화
탭별 설정 해석기 도입	AgentTabSettingsResolver를 추가해 Cowork/Code 분기(검증 활성/Code 전용 도구 비활성)를 단일 경로로 정리
L4 통합 회귀 보강	PermissionModeCatalogTests/PermissionModePresentationCatalogTests/SlashCommandCatalogTests를 추가하고 deny 우선 규칙을 OperationModePolicyTests에 반영해 권한·슬래시 회귀망을 강화
권한 팝업 핵심 4모드 정렬	권한 팝업을 소극 활용/적극 활용/계획 중심/완전 자동 중심으로 단순화하고 활용하지 않음/질문 없이 진행은 고급 모드 접힘 섹션으로 분리
slash 스크롤 체감 개선	휠/방향키 이동 시 전체 재렌더링을 제거하고 선택 하이라이트만 갱신하도록 바꿔 / 팝업 스크롤 반응성과 안정성을 개선
slash 팝업 밀도 압축 2단계	/ 팝업 폭/높이/패딩과 항목 폰트/행 높이를 축소해 Codex형 컴팩트 밀도와 스캔 속도를 강화
권한 팝업 밀도 압축 2단계	권한 팝업의 섹션/요약/예외/거부 카드와 권한 행 타이포를 압축해 슬래시 팝업과 동일한 컴팩트 리듬으로 정렬
입력 하단/모델 선택 컴팩트 정렬	입력 박스·모델 선택 버튼·인라인 설정 패널·전송 버튼 크기를 축소해 Codex형 컴포저 밀도로 정렬
로직 안정화 회귀 보강	ContextCondenserTests와 LlmRuntimeOverrideTests를 보강해 compact 실동작과 vLLM 암호화 API키/SSL 우회 해석 규칙을 회귀 검증
권한 패턴 구문 호환성 보강	권한 규칙 파서를 tool@pattern 외 `tool
권한 모드 별칭 정합 보강	/permissions, /allowed-tools에서 none/passive/active/planning/fullauto/silent 별칭을 지원하고 카탈로그 정규화와 일치시킴
권한 기본값 정책 정렬	신규/초기 상태의 기본 권한을 활용하지 않음(Deny)으로 변경하고 AppState 기본/요약 상태와 slash 사용 가이드를 동일 체계로 정렬
탭 전환 빈 대화 누적 방지	탭 전환 중 생성되는 무의미한 빈 대화를 저장 대상에서 제외하고, 목록에서도 빈 노이즈 항목을 숨겨 이력 누적 체감 버그를 완화
권한 팝업 즉시반영 정렬	권한 팝업에 활용하지 않음을 핵심 영역 맨 위에 배치하고, 대화 권한이 없을 때도 탭 기본값(Deny/DefaultAgentPermission)을 즉시 반영하도록 로딩 경로를 보강
권한 색상 체계 통일	권한 요약 카드/상단 배너에서 모드별 색상(Deny=녹색, Passive=파랑, Active=녹색, Plan=보라, FullAuto=주황, Silent=빨강)을 팝업 체계와 일치시킴
슬래시 네비게이션 입력 보강	InputBox 포커스 상태에서도 방향키/Page/Home/End/Tab이 슬래시 목록 탐색에 즉시 반영되도록 키 처리 경로를 통합하고, 모든 그룹 접힘 상태에서 휠 스크롤 fallback을 추가
사내/사외 모드 회귀 보강	operationMode 전환 직후 WebSearch 동작 반영과 URL 판별 경계(HTTP/파일/mailto) 테스트를 추가해 내부 차단 정책의 즉시성/정확성을 강화
AX Agent 설정창 오픈 안정화	ToggleSwitch를 전역 리소스로 승격해 AX Agent 창 초기화 시 리소스 누락 예외를 방지하고, AX Agent 설정창에는 테마 사전만 안전 주입하도록 오픈 경로를 보강
권한 순환/슬래시 스크롤 체감 보강	claw-code 기준으로 권한 순환에서 고위험 질문 없이 진행을 기본 순환에서 분리하고, / 팝업 휠 스크롤 시 뷰포트 기준 선택 동기화를 추가해 스크롤 사용성을 개선
권한 팝업 상세영역 단순화	권한 팝업의 요약/예외/최근거부를 개별 섹션에서 단일 상세 정보 섹션으로 통합해 기본 화면 밀도를 낮추고 핵심 모드 선택 흐름을 우선화
권한 팝업 밀도/정렬 미세조정	권한 행의 패딩·폰트·아이콘·체크마크 간격을 컴팩트하게 재정렬하고 요약 카드 타이포를 축소해 claw-code 스타일의 빠른 스캔 밀도를 강화
Slash palette 상태 분리 시작	ChatWindow에 몰려 있던 slash 상태를 SlashPaletteState로 분리해 이후 Codex/Claude형 composer 개편 기반 마련
런처 이미지 미리보기 추가	# 클립보드 이미지 항목에서 Shift+Enter로 전용 미리보기 창을 열고, 줌·원본 해상도 확인·PNG/JPEG/BMP 저장·클립보드 복사를 지원
검증	dotnet build 경고 0 / 오류 0, dotnet test 436 passed / 0 failed

자세한 내용은 docs/DEVELOPMENT.md의 v0.7.3 항목을 참고하세요.

---

라이선스

MIT License