skaft / ygg / docs

Ygg documentation

Small agent.
Explicit
context.

Local models are first class. Context layers stay inspectable. Customization lives in files, flags, and commands.

core Rust prompt at most 550 B fixed scaffold docs current source, unreleased
01

Start

Install. Pick a model. Work.

Requirements

  • macOS or Linux
  • Rust 1.86 or newer
  • rg on your PATH

Install 0.1.0-alpha

curl --proto '=https' --tlsv1.2 -LsSf \
https://raw.githubusercontent.com/skaft-software/ygg/v0.1.0-alpha/scripts/install.sh | sh

Restart the shell, then run ygg --version.

The installer is pinned to the alpha. The reference below tracks current unreleased source and may be ahead.

Anthropic

export ANTHROPIC_API_KEY='...'
ygg --model claude-sonnet-4-6

OpenAI

export OPENAI_API_KEY='...'
ygg --model gpt-5.4

ChatGPT subscription

ygg --login codex
ygg
Connect a local OpenAI-compatible endpoint

Create ~/.ygg/credentials/custom.json with owner-only permissions.

{
  "base_url": "http://127.0.0.1:8000/v1/",
  "api_key": "",
  "auto_discover": false,
  "models": [{
    "api_name": "Qwen/Qwen3-Coder-Next",
    "display_name": "Qwen3 Coder Next",
    "context_window": 131072,
    "max_output_tokens": 16384,
    "tools": true,
    "parallel_tool_calls": false,
    "vision": false,
    "structured_output": false,
    "reasoning": true
  }]
}
chmod 600 ~/.ygg/credentials/custom.json
ygg --offline --model 'custom/Qwen3 Coder Next'

--offline skips optional startup discovery. Inference still reaches the selected endpoint.

02

Use

Three frontends. One session model.

interactiveygg

Rich terminal UI with native scrollback.

plainygg --plain

Chronological ASCII without cursor control.

printygg -p "review this"

Headless, response-only output.

Keys

Enter
submit, or steer an active run
Ctrl+S
steer an active run
Shift/Alt/Ctrl+Enter
insert a newline
Ctrl+O
toggle reasoning or tool details
Ctrl+C / Ctrl+D / Esc
abort active, close idle
PageUp / PageDown
page transcript
Ctrl+End
jump to newest output
Tab
complete a slash command or @ mention

Slash commands

conversation

/new/resume [id]/tree/checkout <id>/compact

model

/model [id]/cycle-model/thinking [level]/status/cost/cache

view

/theme [name|list|reload]/verbose [on|off]/tool [call-id]/reload

local system

/prompt [name] [arguments]/skills [subcommand]/extensions [reload]/sessions/export [path]

identity

/login [provider]/logout [provider]/name [name]/quit
03

Models

Local first. Cloud ready.

Ygg keeps one conversation model across OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages.

OpenAIAnthropicDeepSeekOpenRouterGroqCerebrasxAITogether AIFireworks AINVIDIAHugging FaceMoonshot AIXiaomiMiniMaxOpenCode Zencustom

Choose

ygg --model provider/model
/model
/cycle-model

Reasoning

Ygg normalizes the selected model's actual capability. Depending on the model, the picker exposes off, on, effort levels, or a budget.

ygg --reasoning high
/thinking
04

Context

You decide what the model sees.

fixed scaffold

At most 550 bytes.

The fixed scaffold covers identity, enabled core tool names, and a terse response contract. The current working directory is added separately. Tool schemas and project context remain explicit layers.

AGENTS.md

Global by default. Project only with trust.

~/.ygg/AGENTS.md loads globally. Workspace files load root to current directory only with --workspace-trusted. Disable all context files with --no-context-files.

compaction

Automatic at 85%.

The default keeps four recent turns. Use /compact at any time. Active skill state survives compaction and resume.

Prompt templates

Markdown or TOML. Deterministic arguments, workspace variables, bounded file includes, and content hashes.

ygg --prompt local-review "focus"
/prompt local-review focus
ygg --debug-prompt --prompt local-review

Skills

Discovery reads metadata only. Loading is explicit. Supporting files under references/ and templates/ load lazily.

/skills search rust review
/skills load local-model-review
/skills active
/skills off local-model-review
05

Tools + safety

Small surface. Explicit authority.

core workspace tools

readeditwriteexecsearch opt-in

The default model-visible surface also includes search_skills, load_skill, and read_skill_resource. Activated skills can add more tools. Paths are workspace-only by default. Command execution has the full authority of your user account. Ygg is not an operating-system sandbox.

review only
ygg --tools read,search \
  --no-context-files --offline
no mutation
ygg --no-edit

Disables edit and write.

no commands
ygg --no-process

--no-shell is the same authority gate.

exact set
ygg --tools read,edit,exec
ygg --exclude-tools write

Default execution timeout is 120 seconds. Persisted tool output defaults to 16 KiB. Unresolved mutating calls after a crash are marked indeterminate and are never replayed automatically.

06

Sessions

Durable. Branchable. Local.

rootprompthead * alternate branch

Conversations are bounded append-only JSONL, namespaced by workspace. Checkout moves the durable head without deleting ancestry.

continue

ygg --continue
ygg --resume
ygg --resume <id>

inspect

ygg sessions list --query review
ygg sessions inspect <id>
ygg sessions tag <id> rust local-model

export + repair

ygg sessions export <id>
ygg sessions repair <id>
ygg sessions delete <id>

Export validates and redacts by default. Delete moves files to a recoverable trash directory. Repair only removes an interrupted final append after writing a private backup.

07

Customize

Everything important is inspectable.

theme~/.ygg/themes/*.toml.ygg/themes/*.toml--theme-dir
prompt~/.ygg/prompts/*.ygg/prompts/*--prompt-template
skill~/.ygg/skills/*/SKILL.md.ygg/skills/*/SKILL.md--skill-dir
extension~/.ygg/extensions/*/extension.toml.ygg/extensions/*/extension.toml--extension-dir

Resolution is global, trusted project, then explicit paths. Later definitions win. Files must be regular and non-symlink. One broken resource becomes a diagnostic instead of blocking startup.

Themes

Ten bundled themes target semantic surfaces, not raw terminal escapes. They adapt across truecolor, ANSI, Unicode, ASCII, light, dark, and plain terminals.

/theme
/theme list
/theme reload

Extensions

Local JSON-RPC 2.0 processes can add tools, commands, hooks, context, status, and renderers. Discovery, enablement, and executable trust are separate.

ygg --extension-dir ./extensions \
  --enable-extension git-tools \
  --trust-extension git-tools
08

Reference

Defaults with nowhere to hide.

built-in→~/.ygg/config.toml→trusted .ygg/config.toml→environment→CLI

Project config can tighten user authority and resource limits, never relax them. It cannot grant executable extension trust.

Common configuration 
model = "custom/Qwen3 Coder Next"
reasoning = "off"
cache_retention = "short"
theme = "zen-mono"
color = "auto"
mouse = "auto"
exec_timeout_secs = 120
max_output_bytes = 16384
context_files = true
offline = false

[compaction]
threshold_fraction = 0.85
keep_recent_turns = 4
Launch controls

--workspace PATHselect workspace root

--workspace-trustedload project config, AGENTS.md, and skills

--model MODELoverride model

--reasoning VALUEoff, on, effort level, or budget

--cache-retention POLICYnone, short, or long

--plainchronological ASCII frontend

-p, --printheadless response-only frontend

--continue / --resume [ID]return to a session

--tools NAMESexact tool allowlist

--no-edit / --no-processremove authority

--offlineskip optional discovery

--helpcomplete current CLI reference

docs track

current source

This is an unreleased reference. The pinned 0.1.0-alpha installer can differ. Check the changelog before relying on source-only behavior.

security ↗ changelog ↗