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가 스트림·구조화 이벤트·최종 응답에 그대로 붙습니다. 구버전의 version-less peer도 v0 호환 경계로 계속 연결됩니다.
환영 화면과 라이브 상태
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 키 안내를 로즈 색으로 띄웁니다.
최상위 명령
| 명령 | 용도 | 주요 옵션 | 코드 |
|---|---|---|---|
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, 인자 없는 /model도 로컬에서 특별 처리합니다. 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/cli/commands/skills.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 클라이언트가 데몬에 인증 상태 리로드를 통지합니다. 인자 없는 /model은 TTY에서 picker를 로컬로 띄운 뒤 선택 결과만 데몬에 전달합니다(core/cli/__init__.py).
picker 키 계약(core/cli/effort_picker.py): Tab이 역할 탭(Primary, Reflection, Mutator)을 순환하고 ↑↓가 모델, ←→가 effort를 고릅니다. Space는 포커스된 역할에 적용하고 picker를 유지하므로 세 역할을 한 세션에서 모두 설정할 수 있습니다. Enter는 staged 선택까지 전부 확정하고 닫으며, Esc는 staged 선택을 포함해 전부 폐기합니다. provider가 바뀌는 전환은 credential source(payg, subscription)를 새 provider 기준으로 다시 추론합니다. /login codex 직후의 GPT 전환이 구독 쿼터로 라우팅되는 근거입니다.
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도 쓰려면 ~/.geode/.env에 GEODE_GATEWAY_ENABLED=true를 추가합니다. |
| 배너 모델과 응답 모델 불일치 | 오래된 데몬 둘 이상이 소켓을 두고 경합 | pkill -f "geode serve" 후 재진입합니다. ps aux | grep은 긴 경로가 잘려 못 잡습니다. |
geode seeds assemble이 exit 2 | wheel 설치에는 scripts/가 없음 | repo 체크아웃에서 실행합니다. |