<img src="https://raw.githubusercontent.com/sandgardenhq/sgai/refs/heads/main/assets/images/logo.png" alt="Sgai Logo" width="200">

Sgai ("Sky"로 발음) - 목표 중심 AI 소프트웨어 팩토리

당신의 목표를 정의하세요. 대시보드를 실행하세요.
AI 에이전트가 당신의 통제 하에 소프트웨어를 계획하고, 실행하며, 검증하는 과정을 지켜보세요.

예시: "드래그 앤 드롭 방식의 이미지 압축기 만들기" → 3명의 에이전트 (개발자, 리뷰어, 디자이너) → 테스트를 통과한 작동하는 앱 → 45분 소요.

📺 4분 데모 시청하기 →

<img style="margin:20px 0;border:1px solid #999;" src="https://github.com/sandgardenhq/sgai/blob/main/assets/screenshots/08-Workspace.png?raw=true" alt="Sgai Dashboard" width="800">

---

Sgai란 무엇인가요?

Sgai는 소프트웨어 개발을 **목표 중심의 멀티 에이전트 워크플로 (multi-agent workflow)**로 전환합니다.

단계별로 프롬프트를 입력하는 대신, 당신은 다음과 같이 수행합니다:

1. 결과물 정의 — "음악 시퀀서 웹 앱 만들기"
2. 에이전트의 작업 계획 — 작업을 시각적인 워크플로 다이어그램 형태의 태스크로 분해
3. 당신의 감독 — 진행 상황을 지켜보고, 에이전트가 가이드가 필요할 때 질문에 답변
4. 성공 확인 — 테스트, 린팅 (linting) 또는 기타 검증을 통해 "완료" 여부 결정

자동 완성 기능이 아닙니다. 채팅창도 아닙니다.
로컬 AI 소프트웨어 팩토리입니다.

---

왜 사용해야 하나요?

• 진행 상황 확인 — 숨겨진 AI 추론 대신 시각적인 워크플로 다이어그램 제공
• 다수의 전문가 — 개발자가 코드를 작성하고, 리뷰어가 이를 확인하며, 보안 분석가가 검증함
• 실행 전 승인 — 계획을 검토하고 질문에 답변한 후, 에이전트가 자율적으로 작업 수행
• 완료 증명 — 작업이 완료로 표시되기 전에 반드시 테스트를 통과해야 함
• 로컬 작동 — 당신의 리포지토리(repository) 내에서 실행되며, 어떤 데이터도 머신을 벗어나지 않음

---

빠른 시작

권장 사항: opencode를 통한 자동 설정

opencode upgrade
opencode auth login
opencode --model anthropic/claude-opus-4-6 run "install Sgai using the instructions from https://github.com/sandgardenhq/sgai/blob/main/INSTALLATION.md"

이 명령은 공식 설치 가이드를 자동으로 실행하고 데모 워크스페이스 (demo workspace)를 시작합니다.

---

수동 설치 (Manual Installation)

필수 사항: Go, Node.js, bun, opencode

권장 사항: jj (버전 관리 (version control)), tmux (세션 관리 (session management)), ripgrep (코드 검색 (code search)), Graphviz (다이어그램 렌더링 (diagram rendering))

go install github.com/sandgardenhq/sgai/cmd/sgai@latest

또는 소스에서 빌드:

git clone https://github.com/sandgardenhq/sgai.git
cd sgai
cd cmd/sgai/webapp && bun install && cd ../../..
...

자세한 내용은 INSTALLATION.md를 참조하세요.

---

실행하기 (Run It)

sgai serve

열기: http://localhost:8080

---

작동 원리 (How It Works)

📺 시청을 선호하시나요? 데모 보기 → https://youtu.be/NYmjhwLUg8Q

1. 목표 생성 (Create a Goal)

대부분의 사용자는 내장된 위저드 (wizard)를 사용하여 목표를 생성합니다.

목표는 GOAL.md에 저장되며, 구현 단계가 아닌 결과 (outcomes)를 기술합니다.

GOAL.md 예시:

---
flow: |
  "backend-developer" -> "code-reviewer"
...

전체 참조를 보려면 GOAL.example.md를 참조하세요.

에이전트 별칭 (Agent Aliases):

기존 에이전트의 프롬프트 (prompt)와 도구 (tools)를 다른 모델과 함께 재사용하는 에이전트 별칭을 생성할 수 있습니다. 이를 통해 동일한 에이전트 역할을 서로 다른 비용/역량 계층 (cost/capability tiers)에서 실행할 수 있습니다.

---
flow: |
  "backend-go-developer-lite" -> "go-readability-reviewer"
...

별칭이 지정된 에이전트는 기본 에이전트의 모든 것(프롬프트, 도구, 스니펫 (snippets))을 상속받지만, 자체적인 모델 설정을 사용합니다. 별칭 에이전트는 워크플로 (workflow) 내에서 다른 에이전트와 동일하게 나타납니다.

2. 에이전트의 작업 계획 (Agents Plan the Work)

<img style="margin:20px 0;border:1px solid #999;" src="https://github.com/sandgardenhq/sgai/blob/main/assets/screenshots/02-ChooseATemplate.png?raw=true" alt="Choose a Template" width="600">

Sgai는 목표를 정의된 역할을 가진 조정된 에이전트들의 워크플로 다이어그램 (workflow diagram)으로 분해합니다.

의존성 (Dependencies)은 명시적입니다. 실행 (Execution)은 가시적입니다.

3. 계획 승인 및 모니터링 (Approve the Plan & Monitor)

<img style="margin:20px 0;border:1px solid #999;" src="https://github.com/sandgardenhq/sgai/blob/main/assets/screenshots/09-Questions.png?raw=true" alt="Agent Questions" width="600">

실행이 시작되기 전에, 에이전트(Agents)들은 사용자의 목표에 대해 명확히 하기 위한 질문을 던집니다.

사용자가 계획을 승인하면, 에이전트들은 자율적으로 작업(Tasks)을 수행하고, 테스트를 실행하며, 완료 여부를 검증합니다.

사용자는 다음과 같은 작업을 할 수 있습니다:

• 실시간 진행 상황 모니터링 (선택 사항)
• 필요한 경우 실행 중단
• 차이점(Diffs) 및 세션 기록 검토
• 다른 접근 방식을 시도하기 위해 세션 포크(Fork)

대부분의 경우, 사용자는 계획을 승인한 뒤 작업이 완료되면 다시 돌아오면 됩니다.

4. _Skills_를 통해 과거 세션으로부터 학습하기

<img style="margin:20px 0;border:1px solid #999;" src="https://github.com/sandgardenhq/sgai/blob/main/assets/screenshots/11-Skills.png?raw=true" alt="Skills Library" width="500">

Sgai는 완료된 세션으로부터 재사용 가능한 기술(Skills)과 코드 스니펫(Code snippets)을 추출합니다. 이를 통해 사용자의 에이전트들은 시간이 지남에 따라 점점 더 똑똑해집니다.

---

AI 하네스(Harness)에서 Sgai 구동하기

Sgai는 AI 에이전트 및 하네스(Harness)를 위해 두 가지 통합 경로인 MCP 도구(MCP tools)와 HTTP 기술(HTTP skills)을 제공합니다. 따라서 Claude Code, Codex 또는 MCP 기능이 있는 모든 어시스턴트가 프로그래밍 방식으로 Sgai를 오케스트레이션(Orchestrate)할 수 있습니다.

MCP 인터페이스

sgai serve를 실행하면, MCP 엔드포인트(Endpoint)가 웹 UI와 동일한 포트에서 사용 가능해집니다:

sgai serve listening on http://127.0.0.1:8080

MCP 엔드포인트는 메인 서버의 /mcp/external에 위치합니다. MCP 기능이 있는 어떤 하네스든 여기에 연결하십시오:

npx mcporter list --http-url http://127.0.0.1:8080/mcp/external --allow-http

OpenCode에서 설정하기:

// opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
...

사용자 정의 --listen-addr를 사용하는 경우 8080을 실제 포트로 교체하십시오.

35개 이상의 도구가 웹 UI의 전체 기능을 미러링합니다 — 워크스페이스 생명주기(Workspace lifecycle), 세션 제어(Session control), 인간 상호작용(Human interaction), 모니터링(Monitoring), 지식(Knowledge), 구성(Compose), 그리고 임시(Adhoc) 기능입니다. 주요 도구는 다음과 같습니다:

도구 (Tool)	기능
list_workspaces	모든 워크스페이스(workspaces)와 그 상태를 탐색
...

기술 (Skills) / HTTP API

Sgai는 일반적인 HTTP를 선호하는 하네스(harnesses)를 위해 agentskills.io 규격을 준수하는 일련의 기술(skills)을 함께 제공합니다.

진입점 (Entrypoint): docs/sgai-skills/using-sgai/SKILL.md

핵심 패턴은 순환적인 탐색(probe)/폴링(poll)/실행(act) 루프입니다:

LOOP:
  1. PROBE  → GET /api/v1/state          # 워크스페이스 + 상태 탐색
  2. CHECK  → pendingQuestion != null?   # 입력이 필요한 워크스페이스가 있는가?
...

탐색(probe) 예시:

curl -s http://127.0.0.1:8080/api/v1/state | jq '.workspaces[0].pendingQuestion'

전체 참조는 docs/sgai-skills/에서 확인할 수 있으며, 워크스페이스 관리(workspace-management), 세션 제어(session-control), 인간 상호작용(human-interaction), 모니터링(monitoring), 지식(knowledge), 구성(compose), 그리고 임시(adhoc) 기능을 다루는 7개의 하위 기술(sub-skills)로 구성되어 있습니다.

---

당신의 코드는 어떻게 되나요?

• 에이전트(Agents)는 당신의 로컬 저장소(local repository) 내부에서 작동합니다.
• 변경 사항은 당신의 버전 관리 시스템(version control)을 거칩니다 (jj를 권장하지만, Git도 작동합니다).
• Sgai는 원격 저장소(remote repositories)로 자동으로 푸시(push)하지 않습니다.

제어권은 당신에게 있습니다.

---

기여하기 (Contributing)

기여는 코드가 아닌 명세(specifications)를 통해 이루어집니다.

왜 코드 대신 명세 파일을 사용하나요?

sgai는 내부적으로 설정 가능한 AI 엔진을 사용하지만, 본질적으로는 주관적인 경험 계층(opinionated experience layer)입니다. 명세는 AI에 의해 구현(implementation)으로 번역됩니다. 소스 코드는 생성된 결과물이며, 신뢰할 수 있는 단일 원천(source of truth)이 아닙니다. 명세에 기여한다는 것은 다음을 의미합니다:

• 우리는 어떻게(how) 만들지가 아니라, 무엇을(what) 만들지에 대해 논의합니다.
• 대화는 고립된 코드 변경보다 더 나은 결과를 이끌어냅니다.
• 유지 관리자(Maintainers)는 현재 구현 사항에 대해 제안을 검증할 수 있습니다.

기여 방법:

1. 명명 규칙을 따라 GOALS/ 디렉토리에 명세 파일을 생성합니다:
   YYYY_MM_DD_summarized_name.md (예: 2025_12_23_add_parallel_execution.md)

2. 당신의 명세 제안이 담긴 PR(Pull Request)을 제출합니다.

3. 메인테이너(Maintainers)가 제안을 검토하며, 승인될 경우 현재 구현 사항에 해당 명세(specification)를 실행하여 검증합니다.

모두를 환영합니다. 질문이 있으신가요? 이슈(issue)를 생성해 주세요.

예시는 GOALS 디렉토리를 참조하세요.

---

질문이 있으신가요?

버그를 발견했거나 기능 요청(feature request)이 있으신가요? 이슈 생성하기 →

아이디어를 논의하거나 직접 만든 것을 공유하고 싶으신가요? 토론 시작하기 →

---

개발 (Development)

개발자 문서(Developer documentation)는 docs/에 있으며, 당연히 Doc Holiday를 통해 생성되었습니다!

---

라이선스 (License)

https://github.com/sandgardenhq/sgai/blob/main/LICENSE

---

정보 (About)

Sgai는 Ulderico Cirello에 의해 만들어졌으며, Sandgarden에서 유지 관리합니다.