Sayknow-CLI autonomous coding-agent hero illustration

Sayknow-CLI

코딩은 사고처럼 느껴져야 합니다.
인터뷰, 검토된 계획, tmux 네이티브 실행, 견고한 검증을 위한 집중형 코딩 에이전트 러너.

Release License: MIT Stars Issues Built with Bun i18n

English · 한국어 · 中文 · 日本語 · Español · Français · Deutsch

Sayknow-CLI character mascot

> Sayknow-CLI는 실험적인 베타 단계 프로젝트입니다. 거친 부분이 있을 수 있으니 중요한 작업에 의존하기 전에 출력 결과를 검증하세요. ## Languages 인터페이스는 **7개 언어** — English, 한국어 (Korean), 中文 (简体 / Simplified Chinese), 日本語 (Japanese), Español (Spanish), Français (French), Deutsch (German) — 로 현지화되어 있습니다. 첫 실행 시 시스템 로케일을 자동으로 감지하며, 언제든지 **Settings → Appearance → Language** 에서 전환하거나 예를 들어 `LANG=ja_JP.UTF-8 skc` 로 실행할 수 있습니다. 번역되지 않은 문자열은 English로 대체되며, 브랜드/기술 이름(Claude, OpenAI, MCP, …)은 모든 로케일에서 그대로 유지됩니다. ## What is Sayknow-CLI? Sayknow-CLI(`skc`)는 외부 코딩 에이전트 하니스입니다. 선택한 저장소나 워크트리에서 실행되며, 에이전트에게 작고 명시적인 워크플로 표면을 제공합니다: ```text deep-interview -> ralplan -> ultragoal └─ optional team execution when parallel tmux workers help ``` 이것은 의도적으로 Codex CLI, Claude Code, OpenCode, Claw Code의 숨겨진 플러그인이 아닙니다. 구조화된 계획, 지속적인 증거, tmux 기반 워커, 또는 격리된 워크트리를 원할 때 이러한 도구들 옆에서 `skc`를 시작하세요. ## Install ```sh npm install -g sayknow-cli # 또는: bun install -g sayknow-cli skc --version ``` 프리빌드 네이티브(macOS·Linux·Windows)가 포함돼 있어 Rust 툴체인이나 빌드가 필요 없습니다. 업데이트는 `npm install -g sayknow-cli@latest` 또는 터미널에서 `skc update`. > 이전에 소스(git clone)로 설치했다면 한 번만 `rm -f ~/.local/bin/skc && npm install -g sayknow-cli`로 전환하세요. 소스/개발 설치는 [영문 README](../../README.md#install-from-source-development) 참고. ## Quick start ```sh # Run directly in the current checkout skc # Use a tmux-backed leader session skc --tmux # Use an isolated worktree for risky or reviewable work # --worktree takes an optional branch-like name, not a filesystem path. skc --tmux --worktree my-task-branch # If you already created a worktree directory, launch from that directory instead. cd ../my-task-worktree && skc --tmux ``` SKC 세션 내부에서는, 공개 워크플로 표면을 사용하세요: ```text /skill:deep-interview clarify ambiguous requirements /skill:ralplan build and critique the implementation plan skc ultragoal create-goals --brief-file skc ultragoal complete-goals ``` 조율된 tmux 워커가 실질적으로 도움이 될 때만 `skc team ...`을 추가하세요. ## Core capabilities - **추측하기 전에 인터뷰**: `deep-interview`는 모호한 요청을 구체적인 요구사항으로 바꿉니다. - **변경하기 전에 계획**: `ralplan`은 코드 변경 전에 접근 방식을 검토합니다. - **증거와 함께 실행**: `ultragoal`은 목표, 수정, 점검, 완료 증거를 추적합니다. - **유용할 때 병렬화**: `team`은 더 큰 작업을 위해 tmux 기반 워커를 조율합니다. - **외부에서 검토 가능하게 유지**: 다른 에이전트 런타임을 패치하지 않고 선택한 저장소나 워크트리에서 실행합니다. - **공급자가 실패해도 계속 진행**: 기본 모델이 막히면(자격 증명 없음, 할당량 소진, 인증·서버 오류) 다른 공급자의 모델로 세션을 이어 갑니다. 이 체인은 `/fallback`으로 확인하고 편집할 수 있습니다. 재시작이나 일시적 실패로 중단된 단계는 같은 모델에서 한 번 자동으로 재개됩니다. Z.AI `1113` 같은 할당량 응답은 재시도 예산을 소모하지 않고 요청 한 번 만에 다음으로 넘어갑니다. - **긴 세션도 컨텍스트 윈도 안에서**: 압축(compaction) 후 Codex는 `context_length_exceeded`를 향해 계속 불어나는 대신 공급자에게 보이는 새 기준점에서 다시 시작하며, 압축 요약은 공급자가 거부하지 않도록 작성됩니다. - **의미로 코드 찾기**: `locate` 도구는 grep할 이름이 없을 때도 평범한 설명만으로 해당 동작이 어디에 있는지 찾아 줍니다. - **작업을 알맞은 모델로 라우팅**: `/model`로 역할별·세부 용도별 모델을 지정합니다. 서브에이전트 작업은 `specialty`를 선언해 그 종류의 작업에 지정한 모델에서 실행됩니다. - **세션 안에서 PR/MR까지**: `github`와 `gitlab` 도구로 SKC를 벗어나지 않고 풀/머지 리퀘스트를 열고 살펴보며 CI도 확인합니다. - **이 코드에서 테스트가 실행됐음을 증명**: `verification-receipts` 플러그인은 테스트를 실행할 때마다 영수증을 저장하고, 그 뒤로 코드가 바뀌면 알려 줍니다. - **어떤 세션으로든 복귀**: `alt+r` 재개 선택기, 최신 세션을 이어 가는 `ctrl+q`, `/star`, `/fork`, `/rename`, 그리고 Codex·Claude Code 대화 기록을 가져오는 `/import-session`. ## Workflow surface Sayknow-CLI는 네 가지 기본 워크플로 스킬을 제공합니다: | Skill | What it does | | ---------------- | --------------------------------------------------------------------- | | `deep-interview` | 계획이나 코드 변경 전에 모호한 요구사항을 명확히 합니다. | | `ralplan` | 변경 전에 구현 계획을 구축하고 비평합니다. | | `ultragoal` | 실행, 수정, 검증, 증거를 거쳐 목표를 추적합니다. | | `team` | 병렬 실행이 가치가 있을 때 tmux 기반 워커를 조율합니다. | 그리고 네 가지 번들 역할 에이전트: | Agent | What it does | | ----------- | -------------------------------------------------- | | `executor` | 범위가 정해진 구현, 수정, 리팩터. | | `architect` | 읽기 전용 아키텍처 및 코드 리뷰 평가. | | `planner` | 읽기 전용 순서 결정 및 수용 기준. | | `critic` | 읽기 전용 계획 비평 및 실행 가능성 검토. | 광범위한 기본 스킬 동물원은 없습니다: SKC는 이 작은 방법을 더 좋게 만들어 개선됩니다. ## Built-in tools 에이전트는 다음 도구들로 작업합니다. *opt-in*으로 표시된 도구는 **Settings → Tools**(또는 `~/.skc/config.yml`의 해당 키)에서 켜기 전까지 꺼져 있습니다. | Area | Tools | | ---- | ----- | | 파일과 코드 | `read`, `write`, `edit`, `find`, `search`, `locate`(설명으로 코드 찾기), `ast_grep` / `ast_edit`(구문을 인식하는 검색과 재작성), `lsp` | | 셸과 런타임 | `bash`, `eval`(JS/Python 셀), `ssh`, `debug`, `bisect`, `calc` | | 위임과 추적 | `task`(서브에이전트), `subagent`, `job`, `monitor`, `cron`, `irc`(실행 중인 에이전트와 대화), `todo_write`, `goal`, `checkpoint` / `rewind` | | Git 호스팅 | `github`(*opt-in*, `github.enabled`): `gh`를 통한 풀 리퀘스트, 푸시, CI 실행 · `gitlab`(*opt-in*, `gitlab.enabled`, [`glab`](https://gitlab.com/gitlab-org/cli) 필요): `mr_create`(중복을 만들지 않고 이미 열린 MR을 반환), `mr_view`, `mr_list`, `ci_status` — gitlab.com과 셀프 호스팅 인스턴스 지원 | | 웹과 기기 | `web_search`, `browser`, `computer`, `render_mermaid` | | 탐색 | `search_tool_bm25`(숨겨진 도구와 MCP 도구를 필요할 때 활성화), `skill`, `skill_discovery`, `ask` | 한 번의 실행에 쓸 도구 세트는 `--tools read,bash,...`로 고를 수 있으며, 플러그인·커스텀·MCP 도구 이름도 여기에 지정할 수 있습니다. ## Plugins SKC는 플러그인 번들(도구, 훅, 스킬, MCP 서버)을 로드합니다. 번들은 설치 시점에 해시로 검사되고, 이후 파일이 바뀌면 격리됩니다. 관리는 `skc plugin install|list|...`로 합니다. **`verification-receipts`**(이 저장소에 번들로 포함)는 "지금 있는 코드에서 테스트가 실제로 통과했는가?"에 답합니다: - `verification_run`은 지정한 테스트 파일을 `bun test` 또는 `node --test`로 실행하고, 변경할 수 없는 영수증을 저장합니다: 파일별 통과/실패 개수와 작업 트리의 지문(fingerprint). - `verification_status`는 테스트를 다시 실행하지 않고 그 지문을 다시 계산해, `fresh`인지 아니면 코드가 바뀌어 `stale`인지 보고합니다. - `verification_loop`와 그 훅은 백그라운드 `task`가 최신 영수증 없이 끝났을 때 알려 줍니다. 참고용(advisory)이고 POSIX 전용이며, `node --test`를 쓰려면 Node 24.11.1+가 필요합니다. npm 패키지에는 포함되지 않으므로 체크아웃에서 설치하세요: ```sh git clone https://github.com/jaybeyond/Sayknow_CLI.git skc plugin install ./Sayknow_CLI/packages/coding-agent/bundles/verification-receipts --user ``` ## Works beside your existing agent or bot | Tool or bot | Recommended SKC command | Boundary | | ----------- | ----------------------- | -------- | | Codex CLI | `skc --tmux --worktree ` or `skc` | `--worktree`는 SKC가 관리하는 형제 워크트리의 이름을 지정합니다. 기존 경로의 경우 먼저 그곳으로 `cd` 하세요. | | Claude Code | `skc --tmux` or `skc --tmux --worktree ` | SKC는 Claude Code 확장이 되지 않습니다. | | OpenCode | `skc` or `skc --tmux` | 현재로서는 외부 러너 워크플로만 지원합니다. | | Claw Code | `skc --tmux --worktree ` | SKC는 Claw Code에 설치되거나 그것을 대체하지 않습니다. | | External controller / bot | 호환 가능한 구성을 위한 `skc mcp-serve coordinator` 및 `skc setup hermes`, 또는 서브프로세스 워커를 위한 `skc --mode rpc` | MCP/RPC 지원 봇이라면 무엇이든 스크롤백 스크래핑이 아니라 일반 coordinator/RPC 계약을 통해 SKC를 구동합니다. | 일반 서드파티 봇 설정 및 공급자 독립적 스모크에 대해서는 [`docs/bot-integration.md`](docs/bot-integration.md)를 참조하세요. MCP, RPC, ACP, Bridge/HTTPS 표면 전반의 준비도 분류에 대해서는 [`docs/external-control-readiness.md`](docs/external-control-readiness.md)를 참조하세요. 더 낮은 수준의 프로토콜 세부 사항에 대해서는 [`docs/hermes-mcp-bridge.md`](docs/hermes-mcp-bridge.md), [`docs/rpc.md`](docs/rpc.md), [`docs/bridge.md`](docs/bridge.md)를 참조하세요. 원격 운영자 표면 로드맵에 대해서는 [`docs/sayknow-remote.md`](docs/sayknow-remote.md)(웹 스티어링 휠) 및 [`docs/telegram-remote.md`](docs/telegram-remote.md)(Telegram 라이프사이클 버튼)를 참조하세요. ## Configuration 공급자 재시도, 재개, 폴백 동작은 `~/.skc/config.yml`에서 설정합니다(아래 값이 기본값입니다): ```yaml retry: requestMaxRetries: 4 streamMaxRetries: 100 maxRetries: 3 maxDelayMs: 300000 autoResume: true # 중단된 단계를 같은 모델에서 한 번 재개 maxSilentTimeouts: 3 # 출력 없는 타임아웃이 이 횟수만큼 나면 중단 fallback: auto: true # 기본 모델이 막히면 로그인된 다른 공급자로 계속 진행 maxAttempts: 3 # 체인의 다음 모델로 넘어가기 전 모델당 시도 횟수 ``` `requestMaxRetries`는 스트림이 설정되기 전에 적용됩니다. `streamMaxRetries`는 재생 안전한 일시적 스트림 실패에만 적용됩니다. 잘못된 인증, 지원되지 않는 모델/공급자, 잘못된 형식의 요청, 컨텍스트 오버플로, 사용자 중단, 영구적인 할당량 실패는 현재 모델에서 즉시 실패(fail-fast)합니다. `fallback.auto`가 켜져 있으면 막힌 기본 모델은 체인의 다음 모델로 넘겨집니다(`/fallback`으로 확인하고 편집할 수 있습니다). ## TUI identity 기본 TUI 정체성은 SKC **ink-octopus** 테마 — 문어 먹물: 따뜻한 흑연색, 종이색 글자, 호박색 강조 하나 — 로 다크 터미널에 적용되며, 라이트 터미널에는 **blue-octopus**가 적용됩니다. 더 어둡고 고대비 팔레트를 선호하는 사람들을 위해 따뜻한 **red-octopus** 변형도 번들로 제공됩니다. 세 가지 추가 마이그레이션 테마 — `claude-code`, `codex`, `opencode` — 는 쉬운 눈 마이그레이션을 위해 해당 도구들의 모습을 그대로 따르며 Settings 또는 `/theme`에서 선택할 수 있습니다. 명시적인 사용자 테마 설정이 여전히 우선합니다. ### Bundled theme grid Settings (`Appearance -> Dark theme` / `Light theme`) 또는 `/theme`에서 선택하세요. | Theme | Visual feel | Best fit | | --- | --- | --- | | `blue-octopus` | 촉수 블루 액센트가 있는 파란 문어 팔레트. | 라이트 터미널의 기본값. | | `red-octopus` | 강한 상태 대비를 가진 따뜻한 빨간 문어 변형. | 고대비 다크 대안. | | `ink-octopus` | 문어 먹물 — 따뜻한 흑연색 배경, 종이색 글자, 호박색 강조 하나. | 다크 터미널의 기본값. | | `glow-octopus` | 심해 생물발광 — 틸빛 어둠에 발광 초록, 보조로 보라. | 선명한 강조색을 원하는 다크 터미널. | | `violet-octopus` | 자줏빛 어둠에 라벤더 강조, 보조로 살구색. | 부드럽고 화사한 다크 대안. | | `claude-code` | 테라코타와 핑크 하이라이트가 있는 Claude Code 영감 다크 팔레트. | SKC를 떠나지 않고 Claude Code 근육 기억을 유지. | | `codex` | 더 날카로운 코딩 세션 대비를 가진 선명한 다크 블루그레이 팔레트. | Codex 같은 다크 작업 공간. | | `opencode` | 더 강렬한 터미널 액센트를 가진 OpenCode 영감 다크 팔레트. | 번들 선택기에서의 OpenCode 근육 기억. | ## Development 의존성을 설치하고, 네이티브 바인딩을 빌드하고, 로컬 기본값을 설정하세요: ```sh bun install bun run build:native bun run install:defaults ``` `@sayknow-cli/natives`용 `.node` 바이너리는 gitignore되어 있으며 모든 CLI 호출(`install:defaults`, `dev:link`, 테스트) 전에 필요합니다. ### Canonical: build and link the dev `skc` 전역 `skc` 명령이 **이 체크아웃의 TypeScript 소스**(모든 편집에 즉시 반영되며, 스킬/네이티브가 작동함)를 실행하도록 하려면, `PATH`에 링크하세요: ```sh bun install bun run dev:link ``` `dev:link`는 `skc` → `packages/coding-agent/src/cli.ts`를 `~/.local/bin`에 심볼릭 링크하고(`SKC_DEV_LINK_DIR`로 재정의 가능), 그 관리되는 대상을 교체하며, 다른 `skc`가 여전히 `PATH`에서 더 앞쪽에 있어 그것을 가린다면 경고하고 실패하며, `--smoke-test`를 실행하여 `@sayknow-cli/natives`가 로드되는지 확인합니다. 전체 부트스트랩(install + link + `setup defaults`)을 위해서는 `bun run install:dev`를 사용하세요. 당신의 `skc`가 표류했는지(잘못된 소스, 또는 스킬을 로드할 수 없는 컴파일된 바이너리) 언제든지 확인하세요: ```sh bun run dev:doctor ``` > 일상적인 개발에는 컴파일된 바이너리를 **사용하지 마세요**. `bun --cwd=packages/coding-agent run build`는 독립 실행형 `dist/skc`를 생성하지만, `bun build --compile` 바이너리는 `@sayknow-cli/natives`를 동적으로 로드할 수 없으므로 스킬이 `Cannot find module '@sayknow-cli/natives' from '/$bunfs/root/skc'`로 실패합니다. `dev:link`를 통해 소스에서 실행하면 이를 피할 수 있습니다. 릴리스를 검증할 때만 바이너리를 빌드하세요. 링크 없이 소스에서 직접 CLI를 실행하세요: ```sh bun packages/coding-agent/src/cli.ts --help ``` 기본 워크플로 정의는 커밋된 `.skc` 사본이 아니라 소스에 있습니다: ```text packages/coding-agent/src/defaults/skc/skills//SKILL.md packages/coding-agent/src/prompts/agents/.md ``` 워크플로 정의 또는 리브랜드 표면 변경의 경우, 프로젝트 게이트를 실행하세요: ```sh bun scripts/check-visible-definitions.ts bun scripts/verify-g002-gates.ts bun scripts/rebrand-inventory.ts --strict bun test packages/coding-agent/test/default-skc-definitions.test.ts ``` 패키지별 맵에 대해서는 [`docs/codebase-overview.md`](docs/codebase-overview.md)를 참조하세요. ## Contributors 기여, 버그 보고, 릴리스 검증은 GitHub Issues와 Pull Request를 통해 환영합니다. ## Inspirations and lineage Sayknow-CLI의 기본 TUI 정체성은 문어 가족입니다: 다크 기본값 ink-octopus, 라이트 기본값 blue-octopus, 그리고 red-octopus·glow-octopus·violet-octopus 대안. 또한 해당 도구들에서 옮겨오는 사용자들이 익숙한 모습을 얻도록 팔레트가 그 도구들에서 영감을 받은 `claude-code`, `codex`, `opencode` 마이그레이션 테마를 번들로 제공합니다. 공개 SKC 표면을 의도적으로 집중된 상태로 유지하면서, 작은 에이전트 하니스 계열에서 얻은 교훈을 바탕으로 만들어졌습니다. 역사적 출처 표기는 [`NOTICE.md`](NOTICE.md)에 보관되어 있습니다. ## License MIT. [`LICENSE`](LICENSE)를 참조하세요.