Comanda: 지속적이고 자체 개선되는 에이전트 작업을 위한 터미널 네이티브 런타임

코딩 에이전트가 종료할 수 있도록 만드세요. Comanda는 저장소 내에서 지속적이며 자체적으로 개선되는 에이전트 작업을 위한 터미널 네이티브 런타임입니다. 영어로 워크플로우를 설명하고, 생성된 프로그램을 검사하며, 사용하던 코딩 에이전트를 실행하고, 오직 사용자 자신의 품질 게이트가 작업 완료를 알릴 때만 중지합니다.

Comanda는 영어로 시작하지만, 검사하고 버전 관리하며 개선할 수 있는 YAML 프로그램으로 끝납니다.

# 결과 설명
comanda generate feature-loop.yaml \
"테스트와 보안 검사를 통과할 때까지 이 기능을 구현하세요"
...

설명합니다. 검사합니다. 실행합니다. 개선합니다. 커밋합니다.

장시간 실행되는 작업에는 관찰 가능한 종료 기준이 필요합니다. Comanda의 에이전트 루프는 상태를 유지하고, 이전 결과를 바탕으로 후속 프롬프트를 정교화하며, 각 반복 후에 자동화된 품질 게이트를 실행합니다. 실행을 중단했다가 마지막 체크포인트에서 재개할 수 있습니다.

결정론적 게이트가 루프의 첫 번째 단계에 사용될 파일을 준비하는 경우 quality_gates_before_steps: true를 설정하세요.

; 기본값은 단계 후 검증입니다.

agentic-loop:
config:
name: code-quality-improvement
...

완전한 코드 품질 루프를 실행한 다음, 이를 검사하거나 재개할 수 있습니다:

comanda process examples/agentic-loop/code-quality-loop.yaml
comanda loop status code-quality-improvement
comanda loop resume code-quality-improvement

Comanda는 재시도(retry), 중단(abort), 건너뛰기(skip) 정책; 구문, 보안, 사용자 지정 명령어 게이트; 유한 또는 무한 실행; 그리고 생성자/검사자 또는 종속적인 다중 루프 워크플로우를 지원합니다. 에이전트 루프 예시를 참조하세요.

Claude Code, Gemini CLI, OpenAI Codex, Kimi Code, API 모델 및 로컬 모델을 하나의 워크플로우에서 조정할 수 있습니다. 에이전트에게 개별 역할을 부여하고, 파일을 통하거나 표준 입/출력을 통해 작업을 전달하며, 그 결과를 저장소에 표시 상태로 유지하세요.

parallel-process:
architecture:
input: STDIN
...

git diff | comanda process examples/multi-agent/parallel-review.yaml를 사용하여 이 정확한 병렬 검토 워크플로우를 실행하거나, 다중 에이전트 워크플로우 및 병렬 처리를 탐색하세요.

Git worktrees — 격리된 브랜치에서 병렬 구현을 실행한 후, 그 diff를 검사하고 비교합니다.Codebase indexes — 리포지토리 구조, 심볼, 컨벤션, 운영 노트 및 위험 영역을 포착하여 나중에 에이전트 작업에 사용합니다. 코드가 변경됨에 따라 인덱스를 점진적으로 업데이트하거나 diff할 수 있습니다.Explicit boundaries — 에이전트 루프를 허용된 경로와 명명된 도구로 제한합니다.Quality gates — 자체 테스트, 린터(linter), 보안 검사를 '완료'의 정의로 사용합니다.

comanda index capture --enhance
comanda index diff my-project
comanda index update my-project

워크플로우는 일반 파일입니다. 이를 풀 리퀘스트(pull request)에서 검토하거나, 터미널 또는 CI에서 실행하거나, HTTP를 통해 서비스하거나, MCP 클라이언트에 노출할 수 있습니다.

# 체크인된 워크플로우를 MCP 도구 및 스킬로, 스킬을 MCP 프롬프트로 노출
comanda mcp
# 셸 파이프라인의 일부로 워크플로우 실행
...

MCP 서버 가이드, 서버 API, 그리고 스킬 예시를 참고하세요.

# macOS
brew install kris-hansen/comanda/comanda
# Go
...

macOS, Linux, Windows용 사전 빌드 바이너리는 GitHub Releases에서 확인하세요.

• 자연어 피드백으로부터 워크플로우를 생성하고 개선합니다.
• 유효성 검사를 통해 터미널 또는 Mermaid 그래프로 워크플로우 구조를 렌더링합니다.
• 청킹(chunking)을 사용하여 파일, URL, 이미지, PDF, 데이터베이스 및 배치를 처리합니다.
• 명시적인 허용 목록과 함께 셸 도구를 사용합니다.
• OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, Sakana, Ollama, vLLM, llama.cpp 및 호환 제공업체를 호출합니다.
• 워크플로우를 HTTP 엔드포인트 또는 OpenAI 호환 서버 경로로 실행합니다.

Comanda는 두 가지 상호 보완적인 메모리 모드를 가지고 있습니다:

memory: true
원래 동작을 유지하며, 구성된 COMANDA.md 파일을 전체에 주입합니다.- A
memory:

mapping은 SQLite FTS5 데이터베이스에서 경계가 지정되고 프로젝트 로컬의 의미론적 검색(semantic recall)을 수행합니다. 이는 선택 사항이며, 네임스페이스 범위로 작동하며, 검색된 각 기록은 영구적인 ID와 출처 참조를 유지합니다.

독립적으로 이해할 수 있는 사실들로 프로젝트 메모리를 채우세요:

comanda memory add --namespace project --type decision \
--source architecture-2026-07 "SQLite FTS5를 로컬 영구 메모리 검색에 사용합니다." 
comanda memory search --namespace project "local memory retrieval"

그런 다음 필요한 단계에 대해서만 검색 기능을 활성화하세요:

review:
input: STDIN
model: openai-codex
...

데이터베이스는 기본적으로 .comanda/memory/<namespace>.db에 저장됩니다. comanda memory show <id>를 사용하여 검색된 증거와 그 출처(provenance)를 검사하세요.
전체 워크플로우는 examples/semantic-memory.yaml을 참조하세요. 자동 사실 추출, 중복 제거 및 프로젝트 상태 압축은 다음 레이어로 계획되어 있으며, 이 첫 번째 릴리스에서는 지속성(persistence)을 의도적으로 명시적이고 검사 가능하게 유지합니다.

코드베이스 인덱스는 의미론적 메모리 데이터베이스에 저장되는 탐색 가능한 지식 그래프로 변환될 수 있습니다. 추출은 결정론적이며 로컬에서 이루어집니다: 인덱스 스캔은 EXTRACTED (소스 코드 내 명시적) 또는 INFERRED (이름 해석 또는 선택적 AI 패스) 태그가 지정된 구성 요소, 패키지, 파일, 심볼 및 가져오기(imports)를 에지로 기여합니다.

PostgreSQL DDL (.sql 파일에 포함된 CREATE SCHEMA, CREATE TABLE, 또는 ALTER TABLE ... ADD CONSTRAINT 구문)을 포함하는 저장소는 파서 플러그인 매니페스트가 필요 없이 자동으로 이를 획득합니다: 스키마, 테이블, 열, 기본 키(primary keys), 고유 제약 조건(unique constraints), 그리고 외래 키(foreign keys) (인라인, 테이블 레벨 및 ALTER TABLE을 통해 추가된 것)는 schema/table/column 그래프 노드가 되고, contains, primary_key, unique, foreign_key, references 에지로 연결됩니다. 따라서 comanda graph visualize와 comanda graph explain <table은 애플리케이션 코드와 함께 데이터베이스 스키마를 탐색할 수 있습니다. PostgreSQL 스키마 지원을 참조하세요.

comanda index capture -n myproject --graph # 인덱스 + 그래프를 한 번에
comanda graph build myproject # 또는 등록된 인덱스로 빌드
comanda graph explain Store # 노드와 그 연결 관계
...

comanda graph visualize

복잡한 코드 구조를 탐색하기 위한 로컬호스트 전용 브라우저 뷰를 열어줍니다. 작은 아키텍처 개요로 시작하여, 선택된 노드의 직접적인 근접 영역(neighborhood)만 160개 간격의 페이지로 불러오고 캐시합니다. 검색 기능은 심볼, 파일, 패키지 및 개념을 찾으며, 결과를 선택하면 사용 불가능한 모든 심볼의 혼합물(hairball)을 전송하는 대신 연결된 근접 영역에 초점을 맞춥니다. 인스펙터 모드(Inspector mode)는 또한 선택된 파일, 컴포넌트 또는 심볼에 대한 지속적인 인간의 안내를 수용하며, 그래프 재구축 시에도 살아남고 그래프 인식 에이전트 리콜에 포함됩니다. 이 탐색 계약은 비주얼라이저와 구성된 Comanda 서버를 통해 네이티브 클라이언트에게 제공됩니다:

기본 Map 레이아웃은 아키텍처 및 의존성 방향을 안정적으로 만듭니다: 컴포넌트는 구역처럼 나타나고, 파일이나 심볼로 깊이 들어가면 그 의존성이 계층적 흐름으로 제시됩니다. 방사형의 1~3홉 근접 영역에 더 적합한 질문일 때는 선택적 Focus 레이아웃을 사용하십시오. 라벨은 현재 범위가 읽기 가능할 때 자동으로 나타나며, 밀집된 그래프를 위해 Always와 Selected only 제어 기능을 사용할 수 있습니다. 비주얼라이저는 시스템의 라이트 모드 또는 다크 모드를 따르며, 기기 외부로 코드나 그래프 데이터를 절대 전송하지 않습니다.

Comanda 자체 코드베이스의 아키텍처 개요.

검색하고 결과를 열면 유용한 로컬 구조만 화면에 가져옵니다. 관계 페이지는 브라우저에 캐시되므로, 대규모 리포지토리를 이동할 때 전체 그래프를 다시 로드하는 대신 반응성이 유지됩니다.

동일한 Comanda 그래프에서 추출된 파일 수준의 의존성 흐름.

# 한 번 빌드하고 현재 프로젝트에 대한 로컬 인터랙티브 맵을 열기
comanda index capture ./my-project -n myproject --graph
cd ./my-project
...

GET /graph/overview?namespace=myproject
GET /graph?namespace=myproject
GET /graph/search?namespace=myproject&q=Store
...

localhost 시각화 도구는 Canvas 스타일 클라이언트를 위해 주석(annotation) 엔드포인트를 추가로 노출합니다:

GET /api/v1/annotations?node_id=<node-id>
POST /api/v1/annotations {"node_id":"<node-id>","content":"human guidance"}

브라우저 시각화 도구는 아래 `/api/v1/`에서 동등한 엔드포인트를 제공하며, `127.0.0.1`에만 바인딩됩니다.
그래프 읽기 작업은 데이터베이스를 수정하지 않습니다.

그래프 노드는 메모리 FTS 인덱스에 `graph_node` 레코드로 미러링되므로, 워크플로우 단계는 기존의 메모리 매핑(`types: [graph_node]`)으로 이를 호출할 수 있습니다.

동일한 네임스페이스가 장기적인 에이전트 컨텍스트(agentic context) 역할도 수행합니다. 프로젝트 결정 및 제약 조건으로 시드를 설정하고, 상태를 유지하는 루프가 매 반복마다 그래프 구조와 프로젝트 규칙을 회상하도록 하세요 — 이는 `limit`과 `max_chars`에 의해 제한되므로, 루프는 전체 인덱스 대신 집중된 컨텍스트를 얻게 됩니다.

comanda index capture -n myproject --graph # 인덱스 + 지식 그래프
comanda memory add --namespace myproject --type decision
--source architecture "Keep provider interfaces stable across refactors."
...

예시는 examples/knowledge-graph/를, 설계 문서는 design doc을 참조하세요.

모든 예시를 탐색하거나 comanda.sh를 방문하여 문서와 템플릿을 확인하세요.

make deps
make build
make test

MIT