yottacode

module

v0.1.0 Latest Latest Go to latest Published: May 10, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/yottadynamics/yottacode

Links

Open Source Insights

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

Twenty-eight built-in tools spanning reads, writes, filesystem, search, git helpers (status / diff / blame / log / commit / checkpoints / rollback / file-at-revision), bash, and tests — each with explicit approval policy. See docs/tools.md.

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: 25)
/setup                re-run the setup wizard (reloads config on return)
/init                 draft .yottacode/YOTTACODE.md from the current repo

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 memory list
yottacode run "explain this repository"

Full references: docs/cli.md and docs/tui-slash-commands.md.

Documentation

docs/quickstart.md — first successful session
docs/installation.md — build and install options
docs/configuration.md — flags, env vars, config file, diagnostics
docs/providers.md and docs/models.md — provider/model setup and switching
docs/tools.md — built-in tools and approval behavior
docs/security-and-allow-lists.md — approvals, permissions, path policy, isolation guidance
docs/memory.md and docs/sessions.md — context, recall, persistence
docs/tui-slash-commands.md and docs/cli.md — command reference
docs/architecture.md and docs/development.md — internals and contribution workflow
docs/troubleshooting.md and docs/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 ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

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
adapter
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.
cli
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.
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.
session
tui
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.