Sayknow-CLI
코딩은 사고처럼 느껴져야 합니다.
인터뷰, 검토된 계획, tmux 네이티브 실행, 견고한 검증을 위한 집중형 코딩 에이전트 러너.
English ·
한국어 ·
中文 ·
日本語 ·
Español ·
Français ·
Deutsch
> 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)를 참조하세요.