README
¶
yottacode
Open-source terminal coding agent for your day-to-day engineering work.
yottacode is a single Go binary you run from a project directory. It gives you an interactive terminal UI for day-to-day coding, a scriptable one-shot mode for automation, structured tools for inspecting and editing real repositories, durable sessions, cross-session recall, and explicit memory — all without tying your workflow to one model provider.
Status: pre-1.0 (
0.1.0). The CLI, configuration, and on-disk formats are stabilizing. Pin a tag if you depend on yottacode from scripts.
Getting Started
Pre-built binaries for Linux and macOS (amd64 + arm64) ship on the releases page. Download, extract, and put yottacode on your PATH:
export VERSION=0.1.0
# Swap linux/darwin and amd64/arm64 to match your machine
curl -fsSL https://github.com/yottadynamics/yottacode/releases/download/v${VERSION}/yottacode_${VERSION}_linux_amd64.tar.gz \
| tar -xz
sudo install -m 0755 ./yottacode /usr/local/bin/yottacode
Then launch the interactive setup wizard to pick a provider and model:
yottacode setup
Available archives: yottacode_${VERSION}_{linux,darwin}_{amd64,arm64}.tar.gz. Checksums in SHA256SUMS. Windows users should run yottacode under WSL.
For build-from-source, cross-compilation, manual provider configuration, and other install paths, see docs/installation.md.
Features
Multi-provider support
Native adapters for OpenAI, Anthropic, Google Gemini, xAI (Grok), local Ollama (no API key needed), and ChatGPT OAuth ("Sign in with ChatGPT"). A generic OpenAI-compatible adapter covers NVIDIA NIM, Groq, vLLM, Llama Stack, and any custom /v1 gateway. Swap providers and models mid-session via /provider use and /model.
Self-learning memory layer
Memory is plain text, grep-able, and split across a handful of files. You own USER.md — anything you want yottacode to remember about you globally goes there. Everything else is curated by the agent through memory_save / memory_forget in-conversation, with approval-gated writes for YOTTACODE.md.
| Path | Scope | Maintained by |
|---|---|---|
~/.yottacode/USER.md |
User preferences | You — human-edited only |
~/.yottacode/memory/ |
Global (cross-project) | Agent — auto-curated |
./.yottacode/YOTTACODE.md |
Project | You seed it (or run /init); agent edits go through the approval modal |
~/.yottacode/projects/<slug>/memory/ |
Project | Agent — auto-curated |
Built-in security and approval layer
Mutating tools (writes, edits, shell, git mutations) ask before running, with a syntax-highlighted diff for edits. Project rules support allow / ask / deny (deny wins) for team-shared pre-approvals. Write-path validation confines writes to the working tree, blocks symlink writes, and firewalls secret-bearing paths (.env, ~/.ssh, cloud credentials, auth stores) from both reads and writes.
Tools run on the host — there is no in-process sandbox. For stronger isolation, run yottacode inside a container or devcontainer. See
docs/security-and-allow-lists.md.
Polished terminal UX
Inline rendering keeps your scrollback intact. Markdown-rendered assistant output, slash-command palette with Tab completion, multi-line input via Ctrl+J, input history, and a ? cheatsheet overlay.
Repo-aware tool surface
Thirty built-in tools spanning reads, writes, filesystem, search, git helpers (status / diff / blame / log / commit / checkpoints / rollback / file-at-revision), bash, tests, the todo_write working-plan tracker, and the exit_plan_mode plan-approval surface — each with explicit approval policy. See docs/tools.md.
Typed subagents
Delegate research, code search, and planning to typed subagents that run in their own context window — the parent only sees the final answer, never the child's tool calls or reasoning. Use it to keep the parent's context lean during long conversations. Three built-ins ship: Explore (read-only code search), Plan (drafts an implementation plan), general-purpose (open-ended research). Ship your own under .yottacode/agents/<name>.md (project) or ~/.yottacode/agents/<name>.md (global) with YAML frontmatter declaring tools and an optional model override. /subagents opens an inline picker; Enter views any task's transcript in $PAGER. Mirrors Claude Code's Agent / Task tool surface. See docs/subagents.md.
Background subagents (
run_in_background:truefor fire-and-forget delegation) are an opt-in experimental feature. Enable withyottacode --experimental background_subagents,YOTTACODE_EXPERIMENTAL=background_subagents, or[experimental]in~/.yottacode/config.toml. Foreground delegation is default-on. Seedocs/experimental.md.
Read-only plan mode + auto mode
/plan (or Shift+Tab, or yottacode --permission-mode plan at launch) toggles a read-only research mode that mirrors Claude Code's plan mode: the agent investigates, asks clarifying questions, writes a plan file under ~/.yottacode/plans/<slug>.md, then calls exit_plan_mode (no arguments — the TUI reads the file) to present the plan in an approval card. Approve with [A] to resume execution, or [Y] to enter auto mode and skip per-tool prompts during implementation.
Auto mode enters via Shift+Tab or yottacode --permission-mode auto at launch — useful when you trust a multi-step implementation and want to skip approval friction. run_bash, git_commit, git_checkpoint, and rollback remain in the safety floor and still prompt. Shift+Tab cycles through normal → auto → plan → normal. Mirroring Claude Code, there is no /auto slash command — auto enters via the keybinding or the startup flag, and the permissions-bypass overlay (every tool auto-runs, no iteration cap) enters only via yottacode --dangerously-skip-permissions at startup. See docs/tui-slash-commands.md#plan-mode and docs/tui-slash-commands.md#auto-mode.
Per-prompt checkpoints (/checkpoints / Esc Esc)
Every user message gets an automatic checkpoint capturing the conversation plus the pre-edit contents of any files the agent is about to touch. /checkpoints or double-tap Esc opens a picker over past prompts; pick one and choose to restore conversation, files, or both — the original prompt reappears in the input box so you can edit and resend. Mirrors Claude Code's /rewind. 30-day TTL by default, configurable in config.toml. Bash and git mutations are not tracked. See docs/tui-slash-commands.md#checkpoints---checkpoints--esc-esc.
Custom slash commands
Drop a markdown file into ~/.yottacode/commands/ (user scope) or .yottacode/commands/ (project scope, committable) and it shows up as /<name> in the palette. Bodies support $ARGUMENTS / $1..$9 argument substitution, optional YAML frontmatter (description, argument-hint), and @<path> file references. Subdirectories namespace commands as /ns:name. Mirrors Claude Code's custom-commands surface. See docs/tui-slash-commands.md#custom-commands.
Cross-session recall
/recall <query> runs local SQLite FTS5 search across every saved session. /summarize compacts long sessions after snapshotting the full pre-summary transcript. Per-turn atomic save means crashed terminals don't lose work.
Scriptable one-shot mode
yottacode run "<prompt>" for CI and automation — stdout = answer, stderr = reasoning + tool status. Composes cleanly with pipes and CI logs.
Common commands
In the TUI:
/help show this list
/quit exit yottacode
/clear start a fresh session (current is saved)
/permissions show where permissions are configured
/system show the active system prompt
/sessions open the sessions menu (or /sessions <id|name> to resume directly)
/model open the model picker (subcommands: list [all], <name>)
/provider open the provider menu (subcommands: list, use, add, remove, models)
/doctor probe provider auth and model access
/redo edit and re-run the most recent message
/recall <query> full-text search across every saved session
/summarize compress session history into a structured summary
/memory open the memory picker (USER.md / YOTTACODE.md / saved memories)
/max-iterations <N> cap tool-call iterations per turn (default: 50; auto 4×; --dangerously-skip-permissions removes the cap)
/setup re-run the setup wizard (reloads config on return)
/init draft .yottacode/YOTTACODE.md from the current repo
/plan toggle plan mode (read-only research + plan file) — also Shift+Tab, or `yottacode --permission-mode plan` at launch
/plan list resume an earlier plan from ~/.yottacode/plans/ — also `yottacode --plan-resume <slug>`
Auto mode and the permissions-bypass overlay are intentionally not slash commands (mirroring Claude Code):
- Auto mode —
Shift+Tabfrom normal mode, oryottacode --permission-mode autoat launch - Permissions bypass (every tool auto-runs, no iteration cap, DANGEROUS — deny rules still win) —
yottacode --dangerously-skip-permissionsat launch only; no in-TUI toggle
From the shell:
yottacode doctor
yottacode provider list
yottacode provider use openai
yottacode model list
yottacode sessions list
yottacode sessions resume <id-or-name>
yottacode --continue # most recent session in this directory
yottacode memory list
yottacode run "explain this repository"
Full references: docs/cli.md and docs/tui-slash-commands.md.
Documentation
docs/quickstart.md— first successful sessiondocs/installation.md— build and install optionsdocs/configuration.md— flags, env vars, config file, diagnosticsdocs/providers.mdanddocs/models.md— provider/model setup and switchingdocs/tools.md— built-in tools and approval behaviordocs/security-and-allow-lists.md— approvals, permissions, path policy, isolation guidancedocs/memory.mdanddocs/sessions.md— context, recall, persistencedocs/tui-slash-commands.mdanddocs/cli.md— command referencedocs/architecture.mdanddocs/development.md— internals and contribution workflowdocs/troubleshooting.mdanddocs/faq.md
Development
go test ./... # unit tests
go test -tags=integration ./... # live-provider integration tests
go test -race ./... # race detector
go test -cover ./... # coverage
See docs/development.md for build, test, and adapter-extension guidance.
Contributing
Issues and pull requests are welcome at https://github.com/yottadynamics/yottacode. New capabilities should include tests and docs. Before opening a PR, run:
go test ./...
go vet ./...
License
MIT. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
yotta-models
command
Command yotta-models refreshes internal/catalog/catalog.gen.json by querying each cloud provider's list-models endpoint.
|
Command yotta-models refreshes internal/catalog/catalog.gen.json by querying each cloud provider's list-models endpoint. |
|
yottacode
command
|
|
|
internal
|
|
|
agent
Path-validation helpers for the mutating filesystem tools (write_file, edit_file, mkdir, copy_file, move_file, delete_file).
|
Path-validation helpers for the mutating filesystem tools (write_file, edit_file, mkdir, copy_file, move_file, delete_file). |
|
auth/openai
Package openai implements the OAuth 2.0 Authorization Code + PKCE flow that OpenAI's Codex CLI uses to authenticate to ChatGPT subscriber backends.
|
Package openai implements the OAuth 2.0 Authorization Code + PKCE flow that OpenAI's Codex CLI uses to authenticate to ChatGPT subscriber backends. |
|
catalog
Package catalog is yottacode's source of truth for the set of cloud LLMs the wizard and TUI offer.
|
Package catalog is yottacode's source of truth for the set of cloud LLMs the wizard and TUI offer. |
|
checkpoint
Package checkpoint implements the file + conversation snapshot store behind the TUI's /rewind command and Esc Esc keybinding.
|
Package checkpoint implements the file + conversation snapshot store behind the TUI's /rewind command and Esc Esc keybinding. |
|
config
Package config loads ~/.yottacode/config.toml — the single tunable surface for context-window watermarks, retrieval, and provider profiles.
|
Package config loads ~/.yottacode/config.toml — the single tunable surface for context-window watermarks, retrieval, and provider profiles. |
|
contextwindow
Package contextwindow estimates token usage for a message history and looks up the model's context-window capacity.
|
Package contextwindow estimates token usage for a message history and looks up the model's context-window capacity. |
|
dotenv
Package dotenv loads KEY=VALUE pairs from .env files into a map.
|
Package dotenv loads KEY=VALUE pairs from .env files into a map. |
|
experimental
Package experimental gates not-yet-stable features behind named flags so early adopters can iterate on them while the default experience stays stable.
|
Package experimental gates not-yet-stable features behind named flags so early adopters can iterate on them while the default experience stays stable. |
|
filerefs
Package filerefs implements the @file reference system: when a user types something like "explain @main.go and @internal/foo.go", the agent detects the @-prefixed tokens, reads the matching files from the working directory, and injects their contents into the system prompt so the model sees the file as authoritative context for the turn — no extra read_file tool call required.
|
Package filerefs implements the @file reference system: when a user types something like "explain @main.go and @internal/foo.go", the agent detects the @-prefixed tokens, reads the matching files from the working directory, and injects their contents into the system prompt so the model sees the file as authoritative context for the turn — no extra read_file tool call required. |
|
memory
Package memory loads optional context files that are auto-injected into the system prompt at session start.
|
Package memory loads optional context files that are auto-injected into the system prompt at session start. |
|
oneshot
Package oneshot is the non-interactive entry point: read one prompt, run one agent turn, print the final answer to stdout, exit.
|
Package oneshot is the non-interactive entry point: read one prompt, run one agent turn, print the final answer to stdout, exit. |
|
permissions
Package permissions implements the project-local permissions layer that gates tool calls.
|
Package permissions implements the project-local permissions layer that gates tool calls. |
|
providerops
Package providerops centralizes the provider/model mutation operations the TUI picker and the cobra `yottacode provider` / `yottacode model` subcommands both perform.
|
Package providerops centralizes the provider/model mutation operations the TUI picker and the cobra `yottacode provider` / `yottacode model` subcommands both perform. |
|
recall
Package recall is a tiny full-text index over saved sessions.
|
Package recall is a tiny full-text index over saved sessions. |
|
subagents
Package subagents owns typed-subagent configuration, the per-session task registry for background runs, and the discovery + parsing of agent definition files (`.yottacode/agents/*.md` and `~/.yottacode/agents/*.md`).
|
Package subagents owns typed-subagent configuration, the per-session task registry for background runs, and the discovery + parsing of agent definition files (`.yottacode/agents/*.md` and `~/.yottacode/agents/*.md`). |
|
usercmd
Package usercmd loads user-authored slash commands from markdown files dropped in ~/.yottacode/commands/ (user scope) and <cwd>/.yottacode/commands/ (project scope).
|
Package usercmd loads user-authored slash commands from markdown files dropped in ~/.yottacode/commands/ (user scope) and <cwd>/.yottacode/commands/ (project scope). |
|
version
Package version exposes the build version.
|
Package version exposes the build version. |
|
wizard
Package wizard implements `yottacode setup` — the first-run setup flow.
|
Package wizard implements `yottacode setup` — the first-run setup flow. |