README
¶
scay
scay — a small coding agent. A deliberately tiny, debloated CLI coding agent written in Go. One lean binary, a single third-party dependency (the official MCP SDK), four LLM backends behind one interface.
Philosophy: small, lightweight, fast, readable. The opposite of an IDE-in-a-terminal. Add complexity only when it demonstrably earns its place.
Features
- Four backends, one interface: OpenAI, Anthropic, Google Gemini, and Ollama
(local). Talked to via hand-rolled
net/httpclients — no vendor SDKs. - Streaming everywhere: responses render incrementally on all four backends (SSE or NDJSON), with reasoning blocks still replayed verbatim across turns.
- A tiny command surface: log in, pick a model + thinking effort, manage MCP servers. That's it.
- A safe coding tool set: read, list, grep, edit (unique-match + diff), write, and bash (with an approval gate).
- MCP client: plug in Model Context Protocol servers (stdio + Streamable
HTTP) with
scay mcp add; their tools appear asmcp__server__tool, behind the same approval gate. Global config plus project.mcp.json. - Built to keep going: transient API failures retry with backoff
(honoring
Retry-After), Ctrl-C interrupts a turn without killing the session, and/compactsummarizes long histories in place. - A cute TUI + mascot: optional
scay-tuibinary — streaming chat with markdown rendering, approval modals, and a tiny green block-art octopus in the status bar. Isolated in its own Go module so the core stays lean and scriptable:cd cmd/scay-tui && go build.
Install
Prebuilt binaries (macOS and Linux, once releases are published):
curl -fsSL https://raw.githubusercontent.com/robitec97/scay/main/scripts/install.sh | sh
With Go 1.25+:
go install github.com/robitec97/scay@latest
# or from a checkout:
go build -o scay .
Quickstart
scay auth # pick a provider, paste your API key (stored 0600 under ~/.config/scay)
scay model # pick provider + model + thinking effort
scay # start an interactive session in the current directory
scay -p "..." # one-shot, non-interactive (pipe-friendly)
# optional: MCP servers
scay mcp add fs -- npx -y @modelcontextprotocol/server-filesystem .
scay mcp tools # connect and list what the model will see
API keys can also be supplied via environment variables, which override the
config file: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY
(or GOOGLE_API_KEY), and OLLAMA_HOST.
Status
Early development. See ROADMAP.md for what works today and
what's next, and docs/OVERVIEW.md for the architecture.
License
MIT — see LICENSE.
Documentation
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
agent
Package agent implements scay's tool-use loop: it drives a Provider with a flat conversation history, dispatches the model's tool calls, feeds results back, and stops when the model finishes or an iteration cap is hit.
|
Package agent implements scay's tool-use loop: it drives a Provider with a flat conversation history, dispatches the model's tool calls, feeds results back, and stops when the model finishes or an iteration cap is hit. |
|
cli
Package cli is scay's command-line surface: a tiny stdlib-flag dispatcher over a handful of subcommands (run/REPL, auth, model, mcp, version).
|
Package cli is scay's command-line surface: a tiny stdlib-flag dispatcher over a handful of subcommands (run/REPL, auth, model, mcp, version). |
|
config
Package config loads and saves scay's on-disk settings and resolves the effective credentials for each provider (config file overlaid with env vars).
|
Package config loads and saves scay's on-disk settings and resolves the effective credentials for each provider (config file overlaid with env vars). |
|
mcp
Package mcp connects scay to Model Context Protocol servers (stdio and Streamable HTTP) and exposes their tools to the agent as ordinary tools.Registry entries, namespaced mcp__<server>__<tool>.
|
Package mcp connects scay to Model Context Protocol servers (stdio and Streamable HTTP) and exposes their tools to the agent as ordinary tools.Registry entries, namespaced mcp__<server>__<tool>. |
|
provider
Package provider is scay's single abstraction over four LLM backends (OpenAI, Anthropic, Google Gemini, Ollama).
|
Package provider is scay's single abstraction over four LLM backends (OpenAI, Anthropic, Google Gemini, Ollama). |
|
tools
Package tools implements scay's built-in coding tools (read, list, grep, edit, write, bash), a registry that exposes them to the agent, and an approval gate for the side-effecting ones.
|
Package tools implements scay's built-in coding tools (read, list, grep, edit, write, bash), a registry that exposes them to the agent, and an approval gate for the side-effecting ones. |
Click to show internal directories.
Click to hide internal directories.