A minimal, extensible AI coding agent that runs in your terminal. People usually just call it Zyn.
Zyn reads your code, edits files, runs commands, and asks you questions when a decision is genuinely yours to make. It works with 13+ model providers out of the box — including several that are completely free and need no API key.
❯ add input validation to the signup endpoint
Let me look at the current handler first.
✓ Read src/routes/signup.js 41ms
Adding validation before the database call.
✓ Edited the file src/routes/signup.js 28ms
+14 -2
+ if (!isEmail(body.email)) {
+ return res.status(400).json({ error: "Invalid email" });
+ }
✓ Ran npm test 2.1s
12 passing
Added email and password-length checks. Tests pass.
zen/big-pickle · ██░░░░░░ 18% · 23k/128k · ↑4.2k ↓890 · 3 turns
Zyn is built to be a serious agent — boring and reliable rather than flashy.
Guardrails that are enforced, not requested. A workspace sandbox stops the agent from touching files outside your project — ../ traversal, absolute paths, and symlinks that point out are all rejected in code, not just forbidden in a prompt. Risky shell commands need your explicit approval before they run, and a static classifier double-checks the model's own judgement.
Memory that survives. Every conversation is saved automatically, scoped per project, and resumes exactly where it left off — transcript, token counters and all. Long conversations are compacted into a structured 14-section handoff document that preserves the expensive things a summary drops: decisions, failed attempts, and user feedback.
Zero dependencies. The TUI uses a custom ANSI renderer — no Ink, no React, no heavy framework. RAM usage is ~15-25MB vs 100+MB with Ink-based TUIs. No scroll-loop bugs, no text duplication, no resize issues.
Extensible without forking. Add a tool, a slash command, a provider, a skill, or an MCP server — most of them with no code at all. The skill format matches Claude Code and Codex, so skills are portable. Use Zyn as a library and drive the loop yourself.
Observable. Notable events are written to daily JSON logs with secret redaction. Provider failures are retried with backoff; auth errors are not. A real test suite covers the sandbox, the classifier, every tool, and the full loop.
Free to try, cheap to run. The default provider serves capable models with no API key. Local models via Ollama or LM Studio need none either.
This repository ships a complete manual in docs/. Read it in order when you are new, or jump to a page when you need it.
| Page | What you will learn |
|---|---|
| docs/README.md | Documentation index and reading paths |
| docs/getting-started.md | Install, first run, a guided tour |
| docs/tui.md | The interface, the status bar, themes, keys |
| docs/providers.md | All 13 providers, keys, custom endpoints |
| docs/commands.md | Every slash command, in depth |
| docs/tools.md | Every tool, its parameters, and best practices |
| docs/sessions.md | Saving, resuming, pruning, file format |
| docs/compaction.md | Context limits and the 14-section handoff |
| docs/safety.md | Sandbox, command approval, logs, AGENTS.md |
| docs/configuration.md | config.json keys, env vars, precedence |
| docs/skills.md | Authoring and installing skills |
| docs/mcp.md | Model Context Protocol servers |
| docs/cli.md | Full CLI reference |
| docs/extending.md | Writing tools, providers, using as a library |
| docs/troubleshooting.md | Common problems and fixes |
| docs/glossary.md | Terminology |
Zyn is a loop. It builds a system prompt from your working directory (plus an optional AGENTS.md), sends your message plus the conversation history to a model, and streams the reply into a terminal UI. When the model decides it needs to inspect or change the world, it emits tool calls (read, write, edit, bash, ls, glob, grep, ask, skill, MCP tools). Zyn executes them, feeds the results back, and loops until the model produces a final answer — up to 50 iterations. Everything you do is saved to ~/.zyn/ so you can resume later.
It is built to be boring and reliable: a workspace sandbox stops the agent from touching files outside your project, risky shell commands need your approval, provider failures are retried with backoff, and long conversations are compacted into a structured handoff document before the context window overflows.
| Page | What you will learn |
|---|---|
| getting-started.md | Install, first run, a guided tour |
| tui.md | The interface, the status bar, themes, keys |
| providers.md | All 13 providers, keys, custom endpoints |
| commands.md | Every slash command, in depth |
| tools.md | Every tool, its parameters, and best practices |
| sessions.md | Saving, resuming, pruning, file format |
| compaction.md | Context limits and the 14-section handoff |
| safety.md | Sandbox, command approval, logs, AGENTS.md |
| configuration.md | config.json keys, env vars, precedence |
| skills.md | Authoring and installing skills |
| mcp.md | Model Context Protocol servers |
| cli.md | Full CLI reference |
| extending.md | Writing tools, providers, using as a library |
| troubleshooting.md | Common problems and fixes |
| glossary.md | Terminology |
codeinline is a command, key, file name or identifier.- Code blocks with
bashare things you type in your shell. - Code blocks with no language are file contents.
- Text in
```textblocks is what appears on screen. - Zyn writes its own logs to
~/.zyn/logs/; setZYN_DEBUG=1(or-v) before starting to get verbose detail.
If a page disagrees with what you observe, the code is right and this manual is wrong — please open an issue at https://github.com/toZyn/Zyn/issues.