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 10:05 (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 명령 결과가 새 권한 모드 의미를 표시하도록 정리
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