GEODE의 진입점은 둘입니다. geode(Typer CLI)와 geode-mcp(stdio MCP 서버). 둘 다 pyproject.toml의 [project.scripts]에 선언되어 있고, 각각 core/cli/__init__.py와 core/mcp_server.py로 들어갑니다. 이 페이지는 그 두 표면의 전체 목록입니다.
먼저 정직한 한계 둘. 셸 원샷 geode "프롬프트"는 지원하지 않습니다. 인식되지 않는 첫 토큰은 click의 "No such command" 오류로 끝납니다. 자유 텍스트는 bare geode로 들어간 대화형 REPL 안에서 입력합니다. 그리고 geode serve stop 같은 서브커맨드는 없습니다. 데몬 정지 로직은 core/cli/commands/lifecycle.py에 있지만 Typer 표면에 노출되어 있지 않습니다.
2-프로세스 구조
geode (thin CLI) ── Unix socket IPC (~/.geode/cli.sock) ──→ geode serve (데몬) 자유 텍스트 → send_prompt 스트리밍 AgenticLoop, MCP, 스케줄러, 슬래시 → 조립된 command registry가 THIN/daemon 결정 메신저 폴러, CLIPoller
bare geode는 환영 화면을 띄우고 소켓을 조사한 뒤, 데몬이 없으면 자동 기동합니다(start_serve_if_needed, core/cli/ipc_client.py). 동시 기동 경합은 pidfile flock이 막습니다. 그 뒤 thin REPL이 IPC로 붙습니다. 프로토콜은 최대 1 MiB의 줄 단위 JSON인 geode.ipc.v1이고 서버 쪽 상대는 CLIPoller(core/server/ipc_server/poller.py)입니다. 연결 시 지원 기능의 교집합을 협상하고, 각 요청 ID가 스트림·구조화 이벤트·최종 응답에 그대로 붙습니다. v0 envelope는 계속 읽을 수 있지만 세션 설정 적용 기능이 없는 구버전 peer는 실행 전에 명시적으로 거절합니다.
입력과 화면은 CLI가, 실행과 세션 상태는 데몬이 소유합니다. 대화형 로그인은 터미널에서 수행하며 데몬이 브라우저나 비밀 입력을 대신 열지 않습니다. 오류·취소·완료를 구분해 전달하고, 연결이 끊겨 결과를 확인할 수 없으면 같은 작업을 자동으로 재실행하지 않습니다. 요청 취소는 지원 기능을 협상한 뒤 해당 요청 ID에만 적용됩니다. 취소 접수는 작업 종료나 이미 실행한 외부 변경의 복구를 의미하지 않습니다.
환영 화면과 라이브 상태
bare geode가 띄우는 환영 화면은 core/cli/welcome.py의 _welcome_screen이 그립니다. 먼저 Geodi 브랜드 블록(core/ui/mascot.py의 render_mascot)이 나옵니다. 손으로 찍은 픽셀아트 Geodi(로즈 아졸로틀, core/ui/geodi_art.py)를 truecolor 하프블록 스프라이트로 그리고, 오른쪽에 ◆ GEODE v{version} 마크, 모델 · cwd, /help for commands · type naturally 힌트, 그리고 라우팅이 초기화돼 있으면 활성 플랜/쿼터 한 줄을 붙입니다. 이어서 .env 자동 생성, ChatGPT 구독 OAuth 감지, readiness 점검(문제만 표시 — 조용하면 정상), 프로젝트 기억과 사용자 프로파일 초기화가 돌아갑니다.
실행 중 라이브 상태는 core/ui/event_renderer.py가 그리고, 스피너는 core/ui/spinner_glyph.py 단일 소스에서 옵니다(direct 모드 GeodeStatus와 IPC thin-client 트래커가 공유). 시그니처 스피너는 모양이 바뀌지 않는 로즈 젬 ◆입니다. raised-cosine 밝기 밴드가 라벨 위를 2초 주기로 좌→우로 활강합니다(단일 색조, 무지개 아님 — 모양을 순환시키는 글리프는 기계적으로 읽힌다는 Codex/Claude Code의 교훈).
생각 라벨은 맥락을 따릅니다(_thinking_label): reflection > 활성 플랜 스텝 > 위트 순서로, 리플렉션 중에는 Reflecting…, 그다음 진행 중인 플랜 스텝 텍스트(잘림), 없으면 턴 시작 시각으로 시드된 안정적 위트 동명사(Crystallizing, Faceting …) 하나가 턴 내내 유지됩니다. (round N) 접미사와 라이브 (12s) 타이머가 붙습니다. plan_step/replan 이벤트가 오면 진행 플랜 체크리스트(completed / in_progress / pending)가 그려지고, 해당 페이즈 동안 thinking·tool 출력 위에 고정(pinned)된 채 그 아래에 라이브 활동 영역(도구 통계, 알림)이 갱신됩니다.
HITL 승인 프롬프트(core/cli/ipc_client.py의 _handle_approval_request)는 스피너를 잠시 멈추고 ◆ Approval · <tool> (<category>) 헤더에 한 줄 요약, 그리고 y allow · n deny · a always-allow 키 안내를 로즈 색으로 띄웁니다. y는 그 요청 한 번만 허용하며, 반복해서 답해도 상시 허용으로 바뀌지 않습니다. 세션 동안 유지되는 허용은 명시적인 a뿐입니다.
최상위 명령
| 명령 | 용도 | 주요 옵션 | 코드 |
|---|---|---|---|
geode | 환영 화면, 필요 시 serve 자동 기동, thin REPL 진입 | --version, --continue, --resume <id> | core/cli/__init__.py → core/cli/__init__.py |
geode version | 버전 출력 | 없음 | core/cli/typer_commands.py |
geode about | 실행 중인 것의 한 화면 요약. EFFECTIVE 모델, env가 toml을 가리는 경고, 경로, 데몬 소켓 상태 | 없음 | core/cli/typer_commands.py |
geode setup | 최초 설정 마법사. ChatGPT 구독 OAuth(~/.codex/auth.json)를 API 키보다 먼저 감지 | --reset/-r | core/cli/onboarding.py |
geode doctor [target] | 진단. 기본 bootstrap은 Python, PATH, 자격, 데몬 점검. slack은 게이트웨이 점검 | positional bootstrap | slack | core/cli/doctor_bootstrap.py, core/cli/doctor.py |
geode update | 설치 경로 판별 후 uv patch 업데이트 또는 소스 재설치. 떠 있던 serve는 재시작 | --latest, --dry-run, --force/-f, --restart/--no-restart | core/cli/commands/lifecycle.py |
geode uninstall | 런타임 데이터와 CLI 제거 | --dry-run, --force/-f, --keep-config, --keep-data | core/cli/commands/lifecycle.py |
geode init | .geode/ 프로젝트 골격 생성. 프로젝트 타입 자동 감지 | --force/-f | core/cli/typer_init.py |
geode history | 실행 이력과 월간 비용 요약 | --limit/-n, --month/-m YYYY-MM | core/llm/usage_store.py |
geode serve | CLI IPC 데몬. gateway_enabled를 켜면 메신저 폴러도 함께 실행 | --poll/-p | core/wiring/runtime.py → core/cli/typer_serve.py |
geode-eval audit | Petri × GEODE 정렬 감사 실행 | --judge/-j, --auditor/-a, --target/-t, --seeds/-s, --max-turns/-m, --seed-select, --dim-set, --dry-run/--live, --unrestricted, --cache/--no-cache | evals/petri/cli_audit.py |
geode-eval petri | Petri 역할별 모델과 자격 소스 확인·변경 | model, source, reset | evals/petri/cli.py |
geode-eval petri-archive | petri eval 로그를 워크트리 밖으로 보존하고 YAML 요약 작성 | --raw-archive-dir, --summary-dir | evals/petri/cli_audit.py |
geode-evolve outer-bundle | 스캐폴드 탐색 활동을 하나의 타임라인으로 묶어 보는 뷰어 | --limit, --json | evolve/scaffold_search/outer_bundle.py |
geode-evolve scaffold | 스캐폴드 탐색 상태·실행·이력·롤백 | status, run, history, rollback | evolve/scaffold_search/cli_commands.py |
geode-evolve recall | recall pool 조회·저장 | list, show, save | evolve/scaffold_search/recall_cli.py |
geode reindex | 전 프로젝트 sessions.db에서 ~/.geode/search/global.db FTS5 인덱스 재구축 | --projects-root | core/cli/commands/reindex.py |
geode-evolve campaign | 3-arm 스캐폴드 탐색 캠페인 드라이버 | --n, --k, --arms, --dry-run | evolve/scaffold_search/campaign.py |
서브커맨드 그룹
| 그룹 | 서브커맨드 | 용도 | 코드 |
|---|---|---|---|
geode adapters | list / detect-model / stats | 등록된 LLM 어댑터(PAYG, 구독, CLI 경로) 점검과 디스패치 통계 | core/cli/commands/adapters.py |
geode skill | list / create / remove / show | 3단계 스킬 관리. builtin <package>/.geode/skills/, 프로젝트 .geode/skills/, 개인 ~/.geode/skills/ | core/cli/commands/skill.py |
geode config | explain [key] | 설정 레이어별 후보 표. 어느 레이어가 이기고 무엇이 가려졌는지 보여 줍니다 | core/cli/commands/config.py |
geode-eval config | explain [key] / migrate-petri-toml | 평가 설정 조회와 기존 Petri 설정 이전 | evals/config_cli.py |
geode seeds | assemble | cycle-input 시드 풀 조립. repo 체크아웃 전용 래퍼 | core/cli/commands/seed_pool.py |
geode hub | build | 자기개선 허브 정적 페이지 빌드. repo 체크아웃 전용 래퍼 | core/cli/commands/seed_pool.py |
geode-eval audit-seeds | generate / resume / config | 타깃 dim 하나에 대한 시드 생성 파이프라인. 페이즈별 체크포인트에서 재개 가능 | evals/seed_generation/cli.py |
데몬 정지, 상태, 청소는 core/cli/commands/lifecycle.py의 stop_serve / show_status / do_clean이 구현하지만, Typer 서브커맨드로는 노출되지 않습니다. geode update는 설치 교체 전에 stop하고, 실패 시 중지 상태를 유지하며, 성공 시 CLI/IPC 버전 일치를 확인합니다. /status가 데몬과 디스크 사용량 블록을 포함합니다. 수동 정지는 pkill -f "geode serve"입니다.
슬래시 명령
런타임의 명시적 실행 위치와 핸들러는core/slash_routing.py의 COMMAND_REGISTRY가 정의합니다. 평가와 진화 명령은 각각 geode-eval과geode-evolve로 분리됩니다. thin REPL은 /help, /fleet도 로컬에서 특별 처리합니다. core/cli/commands/_state.py의 COMMAND_MAP은 legacy dispatcher action과 별칭을 매핑합니다. 로컬로 처리되지 않은 짧은 명령은 IPC send_command, 장기 명령은send_command_streaming으로 데몬에 전달됩니다.
| 명령 | 별칭 | 실행 위치 | 용도 | 핸들러 |
|---|---|---|---|---|
/help | THIN | 대화형 도움말 | core/cli/commands/_state.py | |
/login | THIN | 플랜과 자격 대시보드. openai, anthropic, google, add, use, route, quota, source | core/cli/commands/login.py | |
/key <value> | THIN | PAYG API 키 빠른 등록(/login의 legacy 별칭) | core/cli/commands/key.py | |
/model | THIN | 모델 확인과 전환. Tab으로 역할(primary, reflection, mutator) 순환 | core/cli/commands/model.py | |
/cognitive | THIN | 세션의 cognitive state와 최근 이벤트 표시 | core/cli/commands/session.py | |
/fleet | THIN | 최근 턴의 서브에이전트 fleet 뷰 | core/cli/dispatcher.py | |
/goal [objective|clear] | DAEMON_RPC | 지속 Goal 조회·생성·empty 전이. 목적 문장은 파싱하지 않고 그대로 저장 | core/cli/commands/goal.py | |
/plan [objective] | DAEMON_STREAM | 현재 advisory plan 조회 또는 도구가 꺼진 structured planner로 계획 생성. 실행하지 않음 | core/server/ipc_server/plan_command.py | |
/grill <decision> | DAEMON_STREAM | 의존성 frontier를 따라 의사결정을 압박 검증하는 grilling 스킬 | core/skills/grilling.py | |
/quit | /exit, /q | daemon | 세션 비용 요약과 함께 종료 | core/cli/dispatcher.py |
/verbose | daemon | verbose 토글 | core/cli/dispatcher.py | |
/schedule | /sched | daemon | 예약 자동화 관리 | core/cli/commands/schedule.py |
/trigger | daemon | 이벤트와 cron 트리거 관리 | core/cli/commands/trigger.py | |
/status | daemon | 모델, 키 상태, MCP 서버, 데몬과 디스크 사용량 | core/cli/dispatcher.py | |
/mcp | daemon | MCP 서버 상태, 도구, 추가 | core/cli/commands/mcp.py | |
/skills | daemon | 스킬 목록, 추가, 리로드 | core/cli/commands/skills.py | |
/skill <name> | daemon | 스킬 호출. context:fork 서브에이전트 실행 지원 | core/cli/commands/skills.py | |
/cost | daemon | LLM 비용 대시보드와 예산 | core/cli/commands/cost.py | |
/resume | daemon | 중단된 세션 재개 | core/cli/commands/session.py | |
/context | /ctx | daemon | 조립된 컨텍스트 계층 표시 | core/cli/commands/session.py |
/apply | daemon | 지원서 관리 | core/cli/commands/session.py | |
/compact | daemon | 대화 컨텍스트 압축 | core/cli/commands/session.py | |
/clear | daemon | 대화 이력 삭제. thin 클라이언트는 IPC 모드에서 --force를 자동 부착 | core/cli/commands/session.py | |
/tasks | /task, /t | daemon | 사용자 태스크 목록 | core/cli/commands/tasks.py |
/login이나 /key가 로컬에서 끝나면 thin 클라이언트가 데몬에 인증 상태 리로드를 통지합니다. 이름 지정, picker, fullscreen의 /model은 같은 적용 경로를 사용합니다. 현재 세션의 모델·effort·source와 보조 역할을 데몬이 검증하고 적용한 뒤 기본값을 저장합니다. project/global은 미래 세션의 기본값 범위이며 다른 실행 중 세션을 바꾸지 않습니다. 적용 거절과 적용 후 저장 실패는 구분해 표시합니다.
picker 키 계약(core/cli/effort_picker.py): Tab이 역할 탭(Primary, Reflection, Mutator)을 순환하고 ↑↓가 모델, ←→가 effort를 고릅니다. Space는 포커스된 역할을 임시 선택하고 picker를 유지하므로 세 역할을 한 세션에서 모두 설정할 수 있습니다. Enter는 staged 선택까지 전부 확정하고 닫으며, Esc는 staged 선택을 포함해 전부 폐기합니다. 같은 공급자 안에서 모델이나 effort를 바꾸면 현재 source를 유지하고, 공급자가 바뀔 때 새 경로를 해석합니다. 연결 시 실제 데몬 workspace를 확인하며 다른 프로젝트는 별도 serve가 필요합니다. 이 계약을 지원하지 않는 구버전 데몬은 재시작 후 다시 연결해야 합니다.
geode-mcp 서버
geode-mcp는 GEODE를 외부 MCP 호스트(Claude Code 등)에 도구로 노출하는 stdio 서버입니다(core/mcp_server.py). repo 루트의 .mcp.json이 이 프로젝트에서 연 Claude Code 세션에 자동 등록하고, 수동 등록은 claude mcp add geode -- geode-mcp입니다. 도구 설명은 core/tools/mcp_tools.json에서 로드합니다.
| 도구 | 파라미터 | 동작 |
|---|---|---|
run_agent | prompt, time_budget_s | GEODE 에이전틱 원샷 1회 실행(run_agentic_oneshot, core/cli/bootstrap.py). text, rounds, termination_reason 반환 |
self_improving_status | 없음 | 읽기 전용. 승격된 baseline.json(promoted SoT, 최신 측정이 아님)과 최근 mutations.jsonl 행 |
self_improving_propose | 없음 | 스캐폴드 변이 1건 제안. 아무것도 쓰지 않고 diff와 rationale만 반환 |
self_improving_apply | mutation_id | 2단계 계약의 확인 단계. 같은 서버 세션 안의 보류 제안만 소비하고, 모르는 id는 {applied: false} |
query_memory | query | GEODE 메모리 계층 검색(core/memory/project.py) |
get_health | 없음 | 버전, 모델, 자격 상태. *_credential_source 필드가 OAuth와 CLI 레인도 정직하게 보고 |
리소스 geode://soul | 없음 | SOUL.md 내용. 없으면 빈 문자열 |
실패 모드
| 증상 | 원인 | 해법 |
|---|---|---|
geode "..."가 No such command | 원샷 미지원 | bare geode로 REPL에 들어가 자유 텍스트를 입력합니다. |
| 외부 채널 메시지가 들어오지 않음 | gateway_enabled 꺼짐 | 로컬 REPL은 그대로 동작합니다. Slack/Discord/Telegram도 쓰려면 게이트웨이를 켭니다. |
| 배너 모델과 응답 모델 불일치 | 오래된 데몬 둘 이상이 소켓을 두고 경합 | pkill -f "geode serve" 후 재진입합니다. ps aux | grep은 긴 경로가 잘려 못 잡습니다. |
geode seeds assemble이 exit 2 | wheel 설치에는 scripts/가 없음 | repo 체크아웃에서 실행합니다. |