mcgravity

AI 지원 코딩을 위한 빠르고 주관이 뚜렷한 TUI (Terminal User Interface).

McGravity는 AI 코딩 도구(Claude Code, Codex, Gemini)를 긴밀한 피드백 루프 내에서 조율합니다: 작은 작업 계획 → 한 번에 하나씩 실행 → 검토 → 재계획. 거대한 프롬프트를 한꺼번에 던지고 결과가 좋기를 바라는 대신, McGravity는 작업을 검증하고 경로를 수정하기 쉬운 원자적 단위(atomic pieces)로 분해합니다.

+------------------------------------------------------------+
| McGravity [Claude Code] |
+--------------------------- Output -------------------------+
...

McGravity는 지속적인 개선 루프를 실행합니다:

flowchart LR
A[Your Task] --> B[Plan]
B --> C[Execute]
...

# bun, npm, pnpm, yarn, 등
npm install -g mcgravity

McGravity를 사용하려면 최소 하나 이상의 AI 코딩 도구가 설치되어 있어야 합니다:

도구	설치 명령어	문서
Claude Code	npm install -g @anthropic-ai/claude-code	claude.ai/code
Codex	npm install -g @openai/codex	openai.com/codex
Gemini CLI	npm install -g @google/gemini-cli	ai.google.dev

cd your-project
mcgravity

처음 실행할 때, McGravity는 사용 가능한 AI 도구를 감지하고 계획(planning) 및 실행(execution)을 위해 어떤 도구를 사용할지 선택하도록 요청합니다.

구현하거나 수정하고 싶은 내용을 입력하세요:

Add a /health endpoint that returns JSON with status and uptime.
Check @src/routes/ for existing patterns.

Enter를 누르면

워크플로우가 시작됩니다.

설치 스크립트는 운영체제(OS)와 아키텍처를 자동으로 감지합니다:

# bun, npm, pnpm, yarn, 등
npm install -g mcgravity

GitHub Releases에서 사용 중인 플랫폼에 맞는 최신 릴리스를 다운로드하여 압축을 풀고 PATH에 추가하세요.

git clone https://github.com/tigranbs/mcgravity.git
cd mcgravity
cargo install --path .

좋은 작업 설명은 구체적이며 관련 파일을 참조합니다:

Add input validation to the user registration form.
- Email must be valid format
- Password minimum 8 characters
...

팁:

• 원하는 내용을 구체적으로 작성하세요
• @를 사용하여 파일을 참조하세요

mentions - 수락 기준 (acceptance criteria) 목록

• 제약 사항 언급 (예: "새로운 의존성(dependencies)을 추가하지 마세요")

@ 입력

그 뒤에 프로젝트 내에서 검색할 파일 이름을 입력하세요:

새로운 API 엔드포인트를 추가하기 위해 @src/config.ts를 업데이트합니다.

퍼지 검색 (Fuzzy search): @config는 src/config.ts를 찾아냅니다.

탐색 (Navigation): Up/Down 또는 j/k를 사용하여 선택하세요.

삽입 (Insert): Tab 또는 Enter를 눌러 경로를 삽입하세요.

취소 (Cancel): Esc를 눌러 닫으세요.

.gitignore 패턴과 일치하는 파일은 제안에서 제외됩니다.

줄 시작 부분에 /를 입력하여 사용 가능한 명령어를 확인하세요:

명령어	설명
/settings	설정 패널 열기
/clear	작업, 출력 및 할 일(todo) 파일 삭제
/exit	McGravity 종료

Ctrl+S를 눌러 설정을 엽니다:

설정	옵션	설명
Planning Model (계획 모델)	Claude, Codex, Gemini	작업을 세분화하기 위한 AI 도구
Execution Model (실행 모델)	Claude, Codex, Gemini	작업을 구현하기 위한 AI 도구
Enter Behavior (엔터 동작)	Submit (제출) / Newline (줄바꿈)	입력창에서 Enter를 눌렀을 때의 동작
Max Iterations (최대 반복 횟수)	1, 3, 5, 10, Unlimited (무제한)	계획→실행(plan→execute) 사이클의 횟수

설정은 .mcgravity/settings.json에 자동으로 저장됩니다.

키	동작
Ctrl+S	설정 열기
Ctrl+C	종료
Esc	실행 중인 흐름 취소 / 유휴 상태 시 종료

키	동작
Enter	작업 제출 (기본값) 또는 줄바꿈 (설정된 경우)
Ctrl+Enter	항상 제출
Ctrl+J	항상 줄바꿈 삽입 (모든 터미널에서 작동)
Shift+Enter	줄바꿈 삽입
@	파일 검색 열기
/	명령 메뉴 열기 (줄 시작 시)

키	동작
Ctrl+Up/Down	출력 스크롤
PageUp/PageDown	페이지 스크롤
Ctrl+Home/End	맨 위/맨 아래로 이동

키	동작
Up/Down 또는 j/k	옵션 탐색
Enter 또는 Space	선택 변경
Esc 또는 q	설정 닫기

flowchart TD
subgraph Input
A[작업 설명 작성]
...

왜 이 접근 방식을 사용하나요?

Focused AI (집중형 AI): 각 단계는 단 하나의 작업만 수행합니다. 플래너(Planner)는 계획만 세우고, 실행기(Executor)는 실행만 합니다.
Atomic tasks (원자적 작업): 작고 검증 가능한 변경 사항을 다룹니다. 검토하기 쉽고, 문제가 발생했을 때 수정하기 용이합니다.
Built-in context (내장된 컨텍스트): 완료된 작업이 다음 계획 주기(Planning cycle)에 정보를 제공하므로, AI는 무엇이 완료되었는지 인지합니다.
Controllable (제어 가능): 언제든지 Esc 키로 취소할 수 있습니다. 최대 반복 횟수(Max iterations)를 설정하세요. 각 주기 후에 검토하십시오.

McGravity는 프로젝트 내에 .mcgravity/ 폴더를 생성합니다:

.mcgravity/
├── settings.json # 사용자 설정
├── task.md # 현재 작업 + 완료된 작업 참조
...

각 작업 파일은 다음을 포함합니다:

# Task 001: Add health endpoint
## Objective
Create a /health endpoint returning JSON status.
...

McGravity를 사용하려면 최소 하나 이상의 AI CLI 도구가 필요합니다. 다음 중 하나를 설치하세요:

npm install -g @anthropic-ai/claude-code # Claude Code
npm install -g @openai/codex # Codex
npm install -g @google/gemini-cli # Gemini

설치 후 McGravity를 다시 시작하십시오.

일부 터미널은 수정 키(Modifier keys)를 올바르게 보고하지 않을 수 있습니다. 다음 방법을 시도해 보세요:

• 줄바꿈을 위해 Ctrl+J 사용 (모든 환경에서 작동)
• 탐색 시 화살표 키 대신 j/k 사용

터미널이 전송하는 값을 확인하려면 디버그 모드(Debug mode)를 활성화하세요:

MCGRAVITY_DEBUG_KEYS=1 mcgravity

줄바꿈을 삽입하는 여러 가지 방법:

방법	설명
Ctrl+J	모든 터미널에서 작동
Shift+Enter	표준 방식 (iPad에서는 작동하지 않을 수 있음)
\ 입력 후 Enter	백슬래시 이스케이프 (Backslash escape)
설정(Settings)	"Enter Behavior"를 "Newline"으로 설정

• 출력 패널(Output panel)에서 에러 메시지를 확인하세요.
• AI CLI가 인증되었는지 확인하세요 (claude --help, codex --help).
• 디버깅을 위해 최대 반복 횟수(Max iterations)를 1로 줄여보세요.
• Esc로 취소한 후 더 간단한 작업을 시도해 보세요.

McGravity는 AI CLI 도구를 사용자의 로컬 머신에서 실행합니다. 사용자의 코드나 API 키를 수집, 저장 또는 전송하지 않습니다. 인증은 사용하는 AI CLI 도구에서 직접 구성하십시오.

MIT

Built with Rust + Ratatui by @tigranbs