Sayknow-CLI

Coding should feel like thinking.
A focused coding-agent runner for interviews, reviewed plans, tmux-native execution, and durable verification.

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

Sayknow-CLI is an experimental, beta-stage project. Expect rough edges and verify outputs before relying on it for important work.

Languages

The interface is localized into 7 languages — English, 한국어 (Korean),
中文 (简体 / Simplified Chinese), 日本語 (Japanese), Español (Spanish),
Français (French), and Deutsch (German). It auto-detects your system locale on
first run; switch any time in Settings → Appearance → Language, or launch
with e.g. LANG=ja_JP.UTF-8 skc. Untranslated strings fall back to English, and
brand/technical names (Claude, OpenAI, protocol labels, …) stay verbatim across all locales.

What is Sayknow-CLI?

Sayknow-CLI (skc) is an external coding-agent harness. It runs from the repository or worktree you choose, then gives the agent a small, explicit workflow surface:

deep-interview -> ralplan -> ultragoal
                         └─ optional team execution when parallel tmux workers help

It is intentionally not a hidden plugin for Codex CLI, Claude Code, OpenCode, or Claw Code. Start skc beside those tools when you want structured planning, persistent evidence, tmux-backed workers, or an isolated worktree.

Install

SKC runs on the Bun runtime, so install Bun first, then SKC:

# 1. Install Bun — the skc runtime (skip if you already have bun >= 1.3.14)
curl -fsSL https://bun.sh/install | bash   # Windows: powershell -c "irm bun.sh/install.ps1|iex"

# 2. Install skc, then verify
bun install -g sayknow-cli       # or: npm install -g sayknow-cli
skc --version

The package bundles prebuilt native addons for macOS (Intel + Apple Silicon),
Linux (x64/arm64), and Windows (x64), so there is no Rust toolchain or build
step. Bun is the one prerequisite: the skc launcher runs on Bun and will not
start without it.

Upgrading

npm install -g sayknow-cli@latest    # or run `skc update` in your terminal

On startup skc shows an Update Available notice when a newer release exists.
Run skc update from your terminal (not inside an skc session) to fetch it.

Coming from an older source install? If you installed earlier by cloning the
repo, switch to the npm build once and updates become one-line from then on:

rm -f ~/.local/bin/skc           # remove the old source-linked command
npm install -g sayknow-cli

Install from source (development)

For contributing or running unreleased code. Requires Bun and
a Rust toolchain (cargo); the native addon is compiled locally.

git clone https://github.com/jaybeyond/Sayknow_CLI.git
cd Sayknow_CLI
bun install
bun run build:native              # compiles @sayknow-cli/natives (~1 min)
bun run install:dev               # links skc into ~/.local/bin + default skills
skc --version

Update a source checkout with git pull && bun run build:native. If skc is
"command not found", ensure ~/.local/bin is on your PATH
(echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && exec $SHELL).

Windows (native install)

On a clean Windows 11 machine, install Bun first, then build from source:

# 1. Install Bun
powershell -c "irm bun.sh/install.ps1|iex"

# 2. Restart the terminal so PATH and the Bun runtime refresh, then confirm Bun
bun --version

# 3. Clone, bootstrap, and verify skc
git clone https://github.com/jaybeyond/Sayknow_CLI.git
cd Sayknow_CLI
bun run install:dev
skc --version
skc --smoke-test

dev:link places the skc launcher on your PATH. That directory must be on
PATH for skc to resolve as a command — restart PowerShell (or sign out/in)
if skc is "not recognized" after install.

Troubleshooting:

• skc reports an old Bun runtime. Re-run the Bun installer above, restart
  the terminal, and confirm bun --version matches what skc --version
  expects. If an older Bun still wins, make sure %USERPROFILE%\.bun\bin is
  first on PATH and remove any stale Bun installs shadowing it.
• skc.exe exists but skc is "not recognized". The launcher is installed
  but not on PATH. Confirm %USERPROFILE%\.bun\bin is listed in
  echo $env:Path, then restart the terminal.

Quick start

# 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

Inside a SKC session, use the public workflow surface:

/skill:deep-interview clarify ambiguous requirements
/skill:ralplan build and critique the implementation plan
skc ultragoal create-goals --brief-file <approved-plan>
skc ultragoal complete-goals

Add skc team ... only when coordinated tmux workers materially help.

Core capabilities

• Interview before guessing: deep-interview turns vague requests into concrete requirements.
• Plan before mutation: ralplan reviews the approach before code changes.
• Execute with evidence: ultragoal tracks goals, revisions, checks, and completion evidence.
• Parallelize when useful: team coordinates tmux-backed workers for larger tasks.
• Stay external and reviewable: run from a chosen repo or worktree without patching another agent runtime.

Workflow surface

Sayknow-CLI ships four default workflow skills:

And four bundled role agents:

No sprawling default skill zoo: SKC improves by making this small method better.

Works beside your existing agent or bot

For generic third-party bot setup and provider-independent smokes, see docs/bot-integration.md. For evaluating Aside as an opt-in search/context retrieval sidecar, see docs/aside-integration.md. For readiness classification across external-control surfaces, see docs/external-control-readiness.md. For lower-level protocol details, see docs/rpc.md and docs/bridge.md. For the remote operator surfaces roadmap, see docs/sayknow-remote.md (web steering wheel) and docs/telegram-remote.md (Telegram lifecycle button).

Configuration

Provider retry budgets live in ~/.skc/config.yml:

retry:
  requestMaxRetries: 4
  streamMaxRetries: 100
  maxRetries: 3
  maxDelayMs: 300000

requestMaxRetries applies before a stream is established. streamMaxRetries applies only to replay-safe transient stream failures. Invalid auth, unsupported models/providers, malformed requests, context overflow, user aborts, and permanent quota failures remain fail-fast.

TUI identity

The default TUI identity is the SKC ink-octopus theme — octopus ink: warm graphite, paper text, one amber accent — for dark terminals, with blue-octopus for light terminals. A warm red-octopus variant is also bundled for those who prefer a darker, high-contrast palette. Three additional migration themes — claude-code, codex, and opencode — mirror the look of those tools for easy eye-migration and are selectable from Settings or /theme. Explicit user theme settings still win.

Bundled theme grid

Pick from Settings (Appearance -> Dark theme / Light theme) or /theme.

Development

Install dependencies, build native bindings, and set up local defaults:

bun install
bun run build:native
bun run install:defaults

The .node binary for @sayknow-cli/natives is gitignored and required before any CLI invocation (install:defaults, dev:link, tests).

Canonical: build and link the dev skc

To make the global skc command run this checkout's TypeScript source (hot to every edit, with skills/natives working), link it onto your PATH:

bun install
bun run dev:link

dev:link symlinks skc → packages/coding-agent/src/cli.ts into ~/.local/bin (override with SKC_DEV_LINK_DIR), replaces that managed target, warns and fails if another skc still shadows it earlier on PATH, and runs --smoke-test to confirm @sayknow-cli/natives loads. Use bun run install:dev for the full bootstrap (install + link + setup defaults).

Check at any time whether your skc has drifted (wrong source, or a compiled binary that can't load skills):

bun run dev:doctor

Do not use the compiled binary for day-to-day development. bun --cwd=packages/coding-agent run build produces a standalone dist/skc, but a bun build --compile binary cannot dynamically load @sayknow-cli/natives, so skills fail with Cannot find module '@sayknow-cli/natives' from '/$bunfs/root/skc'. Running from source via dev:link avoids this. Build the binary only when validating a release.

Run the CLI from source directly without linking:

bun packages/coding-agent/src/cli.ts --help

Default workflow definitions live in source, not committed .skc copies:

packages/coding-agent/src/defaults/skc/skills/<name>/SKILL.md
packages/coding-agent/src/prompts/agents/<role>.md

For workflow-definition or rebrand-surface changes, run the project gates:

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

For a package-by-package map, see docs/codebase-overview.md.

Contributing

Contributions, bug reports, and release validation are welcome through GitHub Issues and Pull Requests.

Inspirations and lineage

Sayknow-CLI's default TUI identity is the octopus family: ink-octopus as the dark default, blue-octopus as the light default, and warm red-octopus, glow-octopus, and violet-octopus alternates. It also bundles claude-code, codex, and opencode migration themes whose palettes are inspired by those tools so users moving from them get a familiar look. It builds on lessons from a small family of agent harnesses while keeping the public SKC surface intentionally focused. Historical attribution is kept in NOTICE.md.

License

MIT — Sayknow-CLI is an independent, MIT-licensed project. See LICENSE.

Sayknow-CLI descends from the original MIT work of Mario Zechner and Can Bölük and has grown well beyond it with its own features, workflows, and brand. As the MIT License requires, the original authors' copyright is retained in LICENSE; historical attribution lives in NOTICE.md.