AgentCrew: macOS를 위한 범용 CLI 오케스트레이션 워크벤치

macOS를 위한 범용 CLI 오케스트레이션 워크벤치 (Universal CLI Orchestration Workbench)

Codex, Claude, Cursor-Agent 등 다양한 AI 도구를 시각화된 워크플로우(Workflow)로 매끄럽게 조직할 뿐만 아니라, **임의의 전통적인 CLI 명령(예: git, npm, docker, ffmpeg 등)을 혼합하여 오케스트레이션(Orchestration)**할 수 있으며, 로컬에서 **개발, 테스트, 배포 및 자동화된 운영(Ops)**의 완전한 폐쇄 루프(Closed Loop)를 완성합니다.

간체 중문 | English

AgentCrew는 특정 AI 채팅 도구를 대체하려는 것이 아니라, 다양한 AI CLI가 더 안정적이고 재사용 가능하며 관찰 가능한 방식으로 협업할 수 있도록 통합된 **오케스트레이션 레이어 (Orchestration Layer)**를 제공합니다.

• SwiftUI를 기반으로 구축되어 가볍고 부드럽게 실행됩니다.
• 시각화된 플로우차트 (Flowchart), 전 과정 실행 모니터링, 로컬 시스템 알림을 지원합니다.

동일한 작업을 두 가지 모드 간에 자유롭게 전환하며 실행 효율성과 지능형 폐쇄 루프를 모두 충족할 수 있습니다:

⚡️ 파이프라인 (Pipeline) 모드: 정적 DAG(Directed Acyclic Graph) 워크플로우를 기반으로 하며 실행 경로가 매우 짧습니다. 목표가 명확하고 단계가 고정되어 있으며, 속도와 비용 제어를 추구하는 표준화된 작업에 적합합니다.
🧠 에이전트 (Agent) 모드: 다회차 동적 실행(Plan -> Execute -> Evaluate -> Replan)을 기반으로 합니다. 실패 원인을 자동으로 진단하고 수정 단계를 자동으로 보완하며, 위험도가 높은 작업(예: 삭제, 대규모 리팩토링) 전에는 **인간 참여 (Human-in-the-loop)**를 위해 대기 상태로 전환됩니다.

경직된 완전 순차 실행을 탈피합니다. AgentCrew는 작업 단계 간의 명시적 의존성 (Run After) 및 암시적 의존성 (Sequential Stage)을 자동으로 분석하여, 병렬 실행이 가능한 단계들을 「Wave (파동)」로 묶어 병렬 성능을 극대화하고 긴 체인의 작업 대기 시간을 대폭 단축합니다.

단 한 줄의 자연어(예: "프로젝트에 JWT 사용자 인증과 단위 테스트를 추가해줘")만 입력하면, 시스템이 자동으로 Implement -> Review -> Fix -> Verify 구조의 단계별 절차를 분해하고 적절한 하위 AI 도구를 자동으로 할당합니다.

AI 도구와 깊은 호환성: Cursor/cursor-agent, Claude, Codex 등 대규모 언어 모델(LLM) CLI를 네이티브로 지원합니다.
극도로 단순한 CLI 환경 (Environment) 설정: 표준 / 내부(Internal) 명령 모드를 원클릭으로 전환할 수 있는 기능을 제공합니다. 현재는 주로 Codex와 Claude에 영향을 미치며, Cursor는 고정된 명령 모드를 유지하고 내장된 환경 프로브(Probe)가 경로 분석을 자동으로 완료합니다.

'AI 도구 전용'이라는 한계를 깨고, AgentCrew의 하단에는 강력한 범용 실행기가 있어 다음과 같은 아키텍처 메커니즘을 통해 만물 오케스트레이션을 구현합니다:

기존 도구 체인과의 매끄러운 연결: git, npm, python, docker, ffmpeg 등 macOS 터미널에서 실행 가능한 모든 명령을 완벽하게 지원합니다.
대규모 언어 모델(LLM)과의 상호 운용: 프롬프트(Prompt)를 플레이스홀더({{prompt}}) 또는 표준 입력(stdin)을 통해 쉘 스크립트(Shell Script)로 안전하게 전달할 수 있습니다. 동시에 단계별 프롬프트(Step Prompt)에서 이전 의존 단계의 컨텍스트(예: {{step:Design.summary}})를 참조할 수 있습니다.
구조화된 컨텍스트 전달: 단순히 표준 출력(stdout)을 다음 단계로 넘기는 것이 아니라, 구조화된 메모리와 공유 상태를 기반으로 필요에 따라 주입하여 가독성, 비용 및 제어 가능성을 모두 고려합니다.
무한한 혼합 오케스트레이션: 예를 들어 Cursor로 코드를 작성하고, npm run test를 실행하여 검증하며, 실패 시 에이전트가 자동으로 에러를 캡처하여 Claude가 분석하고 패치(Patch)를 생성하게 한 뒤, 마지막으로 커스텀 쉘 스크립트를 통해 배포를 완료할 수 있습니다.

지능형 모드 추천: 작업 생성 전, 작업의 복잡도, 위험 수준, 다중 도구 협업 필요성 등의 차원을 기준으로 점수를 매겨 가장 적합한 실행 모드(Agent 또는 Pipeline)를 자동으로 추천하며, 실행 중에도 동적인 전환 제안을 제공합니다.
모드 인사이트 (Mode Insights) 분석 대시보드: 실행 데이터 분석 대시보드가 내장되어 추천 채택률, 모드 분포 및 7일간의 추세를 시각적으로 보여줍니다. 상세 로그를 내보낼 수 있어 팀의 복기 및 엔진 최적화를 지원합니다.

AgentCrew는 이전 단계의 전체 표준 출력(stdout)을 기계적으로 다음 단계에 밀어넣지 않습니다. 대신 실행 결과를 **구조화된 컨텍스트 (Structured Context)**로 축적하여, 정말 가치 있는 부분만을 후속 프롬프트에 주입합니다.

RunContext: 단일 실행 회차 내의 의존성 체인 값 전달을 담당합니다. 후속 단계는 이전 의존 단계의 summary, decisions, artifacts, output.tail, error.tail 등의 필드를 읽을 수 있습니다.
SharedState: 단계(Step) / 스테이지(Stage) / 라운드(Round)를 넘나드는 재사용 가능한 상태 축적을 담당합니다. 동일한 rootSessionID 하에서 decision / fact 등이 여전히 유효하게 유지됩니다.

/artifactRef

/issue

/resource

이후 실행에서 계속 재사용될 수 있습니다.

더 깔끔한 프롬프트 (Prompt): 장황한 프로세스 로그 대신 요약(Summary), 결정(Decision), 그리고 핵심 산출물(Artifact)을 기본적으로 전달합니다. 더 명확한 의존성 경계: {{step:...}}를 통해 의존 체인(Dependency Chain) 상의 Step만 읽을 수 있도록 허용하며, 컨텍스트가 경계 없이 확산되는 것을 방지합니다. 더 안정적인 다회차 실행: Agent 모드에서는 동일한 root session의 공유 상태를 라운드(Round)를 넘어 상속할 수 있어, 매 라운드마다 문제를 처음부터 다시 이해해야 하는 상황을 방지합니다. 더 편리한 디버깅: 런타임 시 .agentcrew/context.md가 생성되며, 공유 상태는 .agentcrew/runs/<rootSessionID>/shared-state.json에 디스크로 저장되고, shared-state.md 미러 파일도 동시에 생성됩니다.

• 구조화된 컨텍스트 참조 (Step Prompt 내):
  {{step:Design.summary}},
  {{step:Review.output.tail:500}}
• 파이프라인(Pipeline) 레벨의 실행 상태 읽기:
  {{pipeline.failed_steps}},
  {{pipeline.last_failed.summary}}
• 재사용 가능한 상태를 명시적으로 보고해야 할 경우, Step에서 step-outbox JSON을 작성하도록 하며, 스케줄러(Scheduler)가 웨이브(Wave) 종료 후 이를 통합 병합(Merge)합니다.

더 완전한 설계 설명은 다음에서 확인할 수 있습니다: docs/shared-state-overview.md

"AI 전용 도구"라는 한계를 깨고, AgentCrew는 시각화 인터페이스를 갖추고 대규모 언어 모델(LLM)의 동적 계획(Dynamic Planning)을 지원하며 상태 관리 기능이 탑재된 강화된 버전의 Make 또는 로컬 Jenkins이기도 합니다.

자동화 워크벤치 (Automation Workbench): 팀에서 자주 사용하는 "코드 구현 -> 코드 리뷰 -> 문제 수정 -> 검증 실행" 과정을 재사용 가능한 표준 파이프라인(Pipeline)으로 고착화합니다. 장기 체인 협업 (Long-chain Collaboration): 동일한 프로젝트 내에서 Claude는 문서 작성을, Cursor는 코드 작성을, 자동화 스크립트는 빌드를 담당하도록 하여 한 번에 작업을 완료합니다. 부분 재시도 (Partial Retry): 수십 단계에 달하는 파이프라인이 마지막 단계에서 실패했을 때, 처음부터 다시 시작할 필요 없이 **스테이지(Stage) 또는 단일 Step 단위로 현장에서 재실행(Re-run)**할 수 있습니다.

경량 로컬 CI/CD (DevOps): 웨이브(Wave)를 활용하여 lint와 test를 병렬로 실행하고, 성공 시 build를 직렬로 실행합니다. 마지막으로 AI를 호출하여 CHANGELOG를 자동 생성하며, 클라우드로 푸시하기 전 사람의 승인(waitingHuman)을 기다리며 대기합니다. 멀티미디어/데이터 배치 처리 (Batch Processing): DAG의 최대 병렬 성능을 활용하여 수십 개의 프로세스(예: ffmpeg)를 동시에 실행해 시간이 오래 걸리는 작업을 처리하거나, 데이터를 병렬로 수집한 후 LLM에게 전달하여 정제, 분석하고 주간 보고서를 이메일로 자동 발송합니다. 지능형 운영 및 장애 자가 치유 (Self-healing): 로컬 또는 원격 서비스를 병렬로 점검하며, 지표 이상으로 인해 Step이 실패하면 Agent 메커니즘을 트리거합니다. 에러를 AI에게 전달하여 진단 보고서 및 수정 명령(Patch Step)을 생성하게 하고, 사람이 승인하면 복구를 실행합니다.

차원	⚡️ Pipeline 모드	🧠 Agent 모드
적용 시나리오	작업이 명확하고 단계가 고정되어 있으며, 속도와 확실성을 추구할 때	요구사항이 모호하고 "구현-검토-수정"의 반복적인 탐색 작업이 필요할 때
계획 생성	일회성으로 고정 생성	매 라운드마다 동적 재계획 (Re-planning)
실패 처리	작업 중단, 프로세스 수정 후 재실행 필요	자동 진단 및 보완(Patch) 및 검증 작업의 동적 생성
협업 방식	명시적 의존성에 따른 직렬/병렬 실행	다중 역할 협업 (Coder/Reviewer/Fixer) + 평가 기반
인적 개입	실패 후 중단 시 원인 파악	중간 상태 차단 (ask_human)을 통한 고위험 작업 승인 지원
비용/속도	🚀 더 빠르고 Token 소모가 적음	🛡 더 견고하고 성공률이 높음 (상대적으로 시간 소요)

flowchart TD
%% 고해상도 스타일 클래스 정의
classDef start_end fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,color:#01579b,rx:10px,ry:10px
...

Pipeline 실행 메커니즘 설명:

고정 생성 (Fixed Generation): Planner가 목표에 따라 모든 Stage 및 그 의존 관계를 포함하는 정적 DAG 그래프를 한 번에 생성합니다. 웨이브 스케줄링 (Wave Scheduling): 시스템이 작업 의존성을 자동으로 분석하여 서로 차단(Blocking)되지 않는 작업들을 하나의 Wave로 묶음으로써 병렬 실행 효율을 극대화합니다. 조기 실패 (Fail-Fast): 특정 Wave에서 심각한 오류가 발생하면 작업을 조기에 중단하여 후속 실행으로 인한 리소스 낭비를 방지합니다. 부분 재시도 (Partial Retry): 작업이 중단된 경우, 사용자는 오류를 조사하고 수정한 뒤 실패한 노드나 Stage부터 즉시 부분 재실행을 시작할 수 있으며, 처음부터 다시 시작할 필요가 없습니다.

flowchart TD
%% 고해상도 스타일 클래스 정의
classDef start_end fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,color:#01579b,rx:10px,ry:10px
...

Agent 점진적 장애 복구 및 자가 치유 전략 (코드 구현 기반의 실제 흐름):

1단계 (Strategy: 처음 계획된 파이프라인 실행): originalPipeline

2단계 (Strategy: 1단계 실패 시, 평가기(Evaluator)가 즉시 대대적인 수정을 가하는 대신, 통과하지 못했거나 건너뛴 단계(Step)만 포함하는 새로운 스테이지(Stage)를 생성하여 원래 경로를 따라 재시도(Retry)함): retryFailedStage

3단계 (Strategy: 재시도 후에도 여전히 실패할 경우, 시스템은 로컬 패치(Local Patch) 메커니즘을 트리거함. 실패한 오류를 추출하여 해당 선행 문제를 해결하기 위한 전용 패치 단계(Patch Step)를 구축하고, 이를 원래 실패한 단계(Step) 앞에 삽입하여 해당 패치가 통과된 후 다음 단계로 진행하도록 보장함): localPatchInsert

4단계/최후 수단 (Strategy: 로컬 패치로도 해결되지 않을 경우, 비로소 LLM 기반의 글로벌 재계획(Global Replan)이 트리거되어, 전체 컨텍스트를 전역적으로 재검토하고 대규모 재구조화(Refactoring)를 수행함): globalReplan

완전 중단: 위의 모든 수단을 동원했음에도 최대 허용 횟수(maxRounds)를 초과하면, 최종적으로 중단(Abort)됩니다.

• macOS 14.0+
• Swift 5.9+
• 터미널에 로그인되어 있으며, 최소 하나 이상의 지원되는 AI CLI(예: Cursor, Claude, Codex)가 구성되어 있어야 함

다음 명령어를 통해 환경을 확인할 수 있습니다:

cursor-agent --version
claude --version
codex --version

AgentCrew는 표준 Swift Package 프로젝트로, 명령줄(CLI)에서 직접 실행하거나 Xcode로 열 수 있습니다.

명령줄을 통한 실행:

git clone https://github.com/YourUsername/AgentCrew.git
cd AgentCrew
swift run AgentCrew

(또는 swift build를 사용하여 빌드 가능)

Xcode를 통한 실행:

1. Package.swift를 더블 클릭합니다.
2. 프로젝트를 열고, 실행 대상으로 Mac을 선택한 뒤 Run (Cmd + R)을 클릭합니다.

• 앱을 실행한 후 Settings로 이동합니다.
• 로컬의 CLI Environment가 올바르게 감지되었는지 확인하고, 필요에 따라 Standard / Internal 명령 모드를 전환합니다 (주로 Codex 및 Claude에 영향을 미침).
• 사이드바 하단의 +를 클릭하여 로컬 코드 저장소(Repository)를 선택합니다.
• AI Pipeline Generator를 클릭하고 작업 요구사항을 입력하거나, 수동으로 파이프라인(Pipeline)을 생성합니다.
• 파이프라인 편집기에서 각 단계(Step)의 도구(Tool)와 프롬프트(Prompt)를 확인합니다 (명령어는 환경에 따라 자동으로 생성되며, Advanced에서 직접 작성하여 덮어쓸 수도 있습니다).
• 우측 상단에서 Pipeline 또는 Agent 모드를 선택합니다.
• Run을 클릭하여 기적을 목격하세요! 📈

본 프로젝트는 SwiftUI로 작성되었으며, 계층형 아키텍처(Layered Architecture) 설계는 다음과 같습니다:

flowchart TB
%% 고해상도 스타일 클래스 정의
classDef layer_ui fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#0d47a1,rx:5px,ry:5px
...

핵심 모듈 설명:

Services/DAGScheduler.swift: 의존 관계(Dependency) 분석 및 웨이브(Wave) 병렬 스케줄링을 담당합니다.
Services/AIPlanner.swift: 대규모 언어 모델(LLM)과 상호작용하여 자연어를 구조화된 실행 단계로 변환하는 역할을 담당합니다.
Services/CLIProfileManager.swift: 서로 다른 환경의 CLI 명령어 파라미터에 대한 적응형 조립(Adaptive Assembly)을 담당합니다.
Services/RunContextStore.swift: 의존성 체인 범위 내의 {{step:...}} 템플릿 파싱, 요약(Summary) / 결정(Decisions) / 아티팩트(Artifacts) 추출, 그리고 .agentcrew/context.md 미러링을 담당합니다.
Services/SharedStateStore.swift: 웨이브 스냅샷(Wave snapshot), 공유 상태 요약(Shared state brief) 주입, step-outbox 병합(Merge), 그리고 동일한 rootSessionID 관리를 담당합니다.

여러 라운드(round)에 걸친 구조화된 상태 지속성(Structured State Persistence)을 지원합니다. ViewModels/AppViewModel.swift

: 전역 상태 관리(Global State Management), 세션 생명주기(Session Lifecycle) 및 패턴 회귀(Pattern Rollback) 분석.

트리거 메커니즘: 동적 라우팅 (Dynamic Routing) DAGScheduler 내에서 시스템은 노드에 사용자 정의 명령(Custom Command)이 설정되어 있는지 여부에 따라 동적 라우팅을 수행하며, AI Runner를 건너뛰고 CommandRunner에 직접 실행을 위임합니다: if step.hasCustomCommand { return try await CommandRunner().execute(...) } // 그렇지 않은 경우에만 Claude 또는 Cursor와 같은 일반적인 AI 도구를 사용합니다.

실행 메커니즘: 순수한 Zsh 서브 프로세스 (Zsh Subprocess) CommandRunner는 하위 레벨에서 zsh -lc를 사용하여 서브 프로세스를 호출하여 명령을 실행하며, 원본 환경 변수( .zprofile / .zshrc 로드)를 그대로 유지합니다. 또한 지능형 경로 분석(Intelligent Path Resolution) 기능이 내장되어 있어, 실행 전 command -v를 통해 실제 절대 경로를 탐색함으로써