README
¶
yottacode
Sovereign AI coding agent for your terminal.
A local-first coding agent that turns issues into tested pull requests while you stay in control of every model, command, and file change.
Model-agnostic · Local-first · Approval-first · GitHub-ready
Getting started • Docs • Providers • Security • GitHub • Contributing
| ● ● ● yottacode |
|
Try it in 60 seconds
Install on Linux or macOS:
curl -fsSL https://yottacode.ai/cli/install.sh | bash
Run setup once:
yottacode setup
Open a repository and try a read-only first task:
cd your-repo
yottacode
Then ask:
Review this repo, identify one low-risk improvement, and show me a plan before editing.
Prefer local models?
Start with Ollama if you want to try yottacode without API keys:
ollama pull qwen2.5-coder # or llama3.1 / deepseek-coder-v2
yottacode setup
Watch the Ollama setup walkthrough: Get started with yottacode and Ollama.
Prefer a hosted provider?
Configure a hosted model during setup, or set the matching environment variable before running yottacode:
export OPENAI_API_KEY=...
yottacode setup
See docs/providers.md for OpenAI, OpenRouter, Anthropic, Gemini, Google Vertex AI, xAI, ChatGPT/Copilot OAuth, Ollama, and other OpenAI-compatible provider setup.
Manual install: pinned version, no installer script
export VERSION=<latest-release> # for example: 0.4.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
install -m 0755 ./yottacode "$HOME/.yottacode/bin/yottacode"
Available archives: yottacode_${VERSION}_{linux,darwin}_{amd64,arm64}.tar.gz; checksums are published in SHA256SUMS on each release.
Windows users should run yottacode under WSL.
More install options: docs/installation.md.
Why yottacode?
| If you want... | yottacode gives you... |
|---|---|
| Model choice | OpenAI, first-class OpenRouter setup, Anthropic, Gemini, Google Vertex AI, xAI, ChatGPT/Copilot OAuth, Ollama, NVIDIA NIM-compatible workflows, vLLM, Together, and other /v1-compatible endpoints |
| Local-first control | Plain-file sessions, memory, approvals, checkpoints, and no telemetry |
| Real repo workflows | Branches, commits, PRs, CI checks, reviews, issues, comments, and isolated worktrees |
| Team-safe automation | Permission rules, path validation, approval previews, plan mode, and rollback checkpoints |
| LSP code intelligence | Local LSP tools for Go, TypeScript/JavaScript, Python, and Rust |
| One-shot automation | yottacode run for CI/CD, ticket resolution, and scripted workflow automation |
| IDE integration | ACP protocol support so yottacode can connect to compatible IDEs and agent frontends |
| Repeatable team workflows | Agent Skills for review checklists, runbooks, releases, migrations, and project-specific playbooks |
Built for control and privacy
Autonomy is useful only when you can trust the loop. yottacode is designed around explicit control: no telemetry, no analytics, plain files under ~/.yottacode/, and model traffic only to providers you configure.
| Control | What it means |
|---|---|
| Approval-first mutations | File writes, shell commands, git operations, and other risky actions pause for approval with a diff, command, or write preview. |
| Path validation | Edits stay inside the working tree and block risky targets like secrets and SSH/cloud credentials. |
| Project permissions | Team rules can allow, ask, or deny specific tools and paths. |
| Plan mode | yottacode can investigate read-only first, produce a plan, and wait before implementation. |
| Checkpoints and rollback | Conversation and repo changes can be checkpointed and rolled back. |
| Local model option | Ollama keeps model traffic on your machine. |
| Plain-file memory | User and project memory live under ~/.yottacode/ and can be inspected or deleted. |
Tools run on the host by default. For stronger shell-command isolation, enable the optional Podman command sandbox with [sandbox] backend = "podman"; it runs approved run_bash/run_tests commands and document subprocess helpers in GHCR-published containers. See docs/sandbox.md and docs/security-and-allow-lists.md.
Provider costs depend on the model you choose. yottacode reports token usage where providers expose it; see docs/cost.md for current cost-tracking behavior.
Use yottacode when your terminal session becomes the workflow
- You are reviewing a PR and need more than a summary. Ask yottacode to read the diff, inspect the touched code, check CI, identify risk, and draft the exact follow-up comment.
- A test is failing and the fix is not obvious. Let yottacode reproduce the failure, trace callers, patch the code, add a regression test, and rerun checks before you commit.
- You need to make a safe infrastructure or GitOps change. Update YAML, Helm values, Terraform, or deployment config with approval-gated diffs instead of copy-pasting snippets between chat and your editor.
- You are jumping into a repo you do not know yet. Use plan mode, LSP, file search, memory, and session recall to map the codebase before anything mutates.
- You want an agent to carry the boring GitHub steps. Turn an issue into a branch, commits, CI inspection, PR body, and reviewer-ready summary without leaving the TUI.
- You need model choice without changing your workflow. Start with local Ollama, use a cloud model when needed, and switch providers mid-session without moving the task to another tool.
Browse reusable workflows in yottacode-skills.
Project status
yottacode is pre-1.0 and actively developed. The CLI, config, and on-disk formats are still stabilizing, but the core terminal workflow is usable today for real repositories.
Good first areas for contributors:
- Docs, examples, and first-run polish.
- Provider adapters and setup diagnostics.
- Workflow skills for real engineering tasks.
- Bug reports from real terminal sessions.
- Tests around approval, GitHub, memory, and worktree behavior.
Support the project
If yottacode looks useful, a GitHub star helps the project reach more developers, attract contributors, and grow the ecosystem. Bug reports, setup feedback, and workflow ideas are just as valuable — open an issue.
Documentation
Browse the full documentation online at yottacode.ai/docs. The guides below are the in-repo copies.
| Section | Description |
|---|---|
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 |
Provider setup and switching |
docs/models.md |
Model configuration |
docs/tools.md |
Built-in tools and approval behavior |
docs/lsp.md |
LSP code intelligence for Go, TypeScript/JavaScript, Python, and Rust |
docs/github.md |
GitHub integration: auth, tools, permissions |
docs/security-and-allow-lists.md |
Approvals, permissions, path policy, isolation |
docs/worktrees.md |
Parallel sessions and .worktreeinclude |
docs/memory.md |
Memory and context persistence |
docs/sessions.md |
Session management and recall |
docs/tui-slash-commands.md |
TUI command reference |
docs/cli.md |
CLI command reference |
docs/run-recipes.md |
yottacode run scripting and CI recipes |
docs/architecture.md |
Internals |
docs/development.md |
Contribution workflow |
docs/troubleshooting.md |
Common issues |
docs/faq.md |
Frequently asked questions |
Contributing
yottacode is built in the open, and contributions are welcome — from typo fixes and docs improvements to provider adapters, workflow skills, and core agent features.
Before opening a PR, please keep changes focused, include tests/docs for behavior changes, and make sure go test ./... and go vet ./... pass.
See CONTRIBUTING.md for the full guide. Please report vulnerabilities privately through SECURITY.md, not public issues.
Development
yottacode is a single, pure-Go binary targeting Go 1.26+ on Linux and macOS (amd64/arm64).
Build
go build -o yottacode ./cmd/yottacode
Test
go test ./... # unit tests — fast, no network
go vet ./... # static checks
govulncheck ./... # reachable dependency/toolchain CVEs
go test -race ./... # race detector
go test -cover ./... # coverage
go test -tags=integration ./... # live-provider tests, needs API keys
Most extension work lands in a documented seam: built-in tools, slash commands, provider adapters, MCP integration, skills, and TUI workflows. See docs/development.md for the full guide — project layout, the model-catalog refresh, provider diagnostics, and release versioning.
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
|
|
|
acp
Package acp implements yottacode as an Agent Client Protocol (ACP) server — a long-lived process hosting N concurrent sessions over one stdio JSON-RPC connection, so yottacode is embeddable in editors that speak ACP (Zed, JetBrains, and others).
|
Package acp implements yottacode as an Agent Client Protocol (ACP) server — a long-lived process hosting N concurrent sessions over one stdio JSON-RPC connection, so yottacode is embeddable in editors that speak ACP (Zed, JetBrains, and others). |
|
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). |
|
agentruntime
Package agentruntime is the shared session-construction layer behind `yottacode run` (internal/oneshot), the TUI (internal/tui), and the ACP server (internal/acp).
|
Package agentruntime is the shared session-construction layer behind `yottacode run` (internal/oneshot), the TUI (internal/tui), and the ACP server (internal/acp). |
|
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. |
|
auth/vertex
Package vertex resolves Google Cloud Application Default Credentials into the short-lived OAuth access tokens Vertex AI requests carry.
|
Package vertex resolves Google Cloud Application Default Credentials into the short-lived OAuth access tokens Vertex AI requests carry. |
|
browser
Package browser drives a real Chromium/Chrome instance over the Chrome DevTools Protocol via go-rod/rod, giving the agent's browser_* tools a pure-Go backend with no Node.js or Playwright dependency.
|
Package browser drives a real Chromium/Chrome instance over the Chrome DevTools Protocol via go-rod/rod, giving the agent's browser_* tools a pure-Go backend with no Node.js or Playwright dependency. |
|
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. |
|
codemap
Package codemap builds a compact, read-only structural index of a workspace.
|
Package codemap builds a compact, read-only structural index of a workspace. |
|
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.
|
Package contextwindow estimates token usage for a message history. |
|
dap
Package dap provides a small yottacode-owned Debug Adapter Protocol client.
|
Package dap provides a small yottacode-owned Debug Adapter Protocol client. |
|
documents
Package documents provides bounded, provenance-rich text extraction from local structured and markup files — CSV, TSV, JSON, JSONL, XML, and HTML — for the read_document agent tool.
|
Package documents provides bounded, provenance-rich text extraction from local structured and markup files — CSV, TSV, JSON, JSONL, XML, and HTML — for the read_document agent tool. |
|
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. |
|
edit/hashline
Package hashline applies edits guarded by content hashes instead of trusting stale offsets alone.
|
Package hashline applies edits guarded by content hashes instead of trusting stale offsets alone. |
|
execguard
Package execguard hardens an already-built *exec.Cmd against the orphaned-descendant hang: a subprocess we invoke (git, gh, ...) can itself fork a child that inherits its stdout/stderr pipes — a git commit launching $EDITOR, a GPG pinentry prompt, an SSH host-key or passphrase prompt, a credential helper.
|
Package execguard hardens an already-built *exec.Cmd against the orphaned-descendant hang: a subprocess we invoke (git, gh, ...) can itself fork a child that inherits its stdout/stderr pipes — a git commit launching $EDITOR, a GPG pinentry prompt, an SSH host-key or passphrase prompt, a credential helper. |
|
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. |
|
github
Package github is the typed adapter between yottacode and GitHub.
|
Package github is the typed adapter between yottacode and GitHub. |
|
lsp
Package lsp provides the small language-server bridge used by yottacode's experimental code-intelligence tools.
|
Package lsp provides the small language-server bridge used by yottacode's experimental code-intelligence tools. |
|
mcp
Package mcp implements yottacode's client for the Model Context Protocol (MCP).
|
Package mcp implements yottacode's client for the Model Context Protocol (MCP). |
|
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. |
|
netguard
Package netguard holds small, dependency-free network-address checks shared by anything that dials a URL it doesn't fully control the destination of — a model-chosen fetch, or a hostname-configured remote server whose DNS could be rebound after the admin approved it.
|
Package netguard holds small, dependency-free network-address checks shared by anything that dials a URL it doesn't fully control the destination of — a model-chosen fetch, or a hostname-configured remote server whose DNS could be rebound after the admin approved it. |
|
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. |
|
promptmacros
Package promptmacros holds the "prompt macro" slash commands shared between internal/tui and internal/acp — the bucket-A commands (/git-commit, /git-push, /git-create-pr, /git-update-pr, /git-create-issue, /git-review-pr, /code-review, /git-implement-issue, /init) that translate a slash invocation into a directive prompt for the agent loop to run as a normal turn.
|
Package promptmacros holds the "prompt macro" slash commands shared between internal/tui and internal/acp — the bucket-A commands (/git-commit, /git-push, /git-create-pr, /git-update-pr, /git-create-issue, /git-review-pr, /code-review, /git-implement-issue, /init) that translate a slash invocation into a directive prompt for the agent loop to run as a normal turn. |
|
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. |
|
sandbox
Package sandbox holds the podman-backed Sandbox implementation (internal/agent.Sandbox) — a session- or worker-scoped rootless container that RunBashTool dispatches commands into via `podman exec` instead of running them directly on the host.
|
Package sandbox holds the podman-backed Sandbox implementation (internal/agent.Sandbox) — a session- or worker-scoped rootless container that RunBashTool dispatches commands into via `podman exec` instead of running them directly on the host. |
|
sandboxcache
Package sandboxcache centralizes host paths shared by sandbox startup and sandboxed tool command preparation.
|
Package sandboxcache centralizes host paths shared by sandbox startup and sandboxed tool command preparation. |
|
sensitive
Sensitive projects — the per-repository opt-out that stops automatic session recall from moving a project's conversations across the network.
|
Sensitive projects — the per-repository opt-out that stops automatic session recall from moving a project's conversations across the network. |
|
shellseg
Package shellseg splits a (possibly compound) shell command into its top-level segments — the pieces separated by &&, ||, ;, and pipes — while respecting quotes, escapes, and $(...)/backtick substitutions so a separator inside a string literal or substitution doesn't split.
|
Package shellseg splits a (possibly compound) shell command into its top-level segments — the pieces separated by &&, ||, ;, and pipes — while respecting quotes, escapes, and $(...)/backtick substitutions so a separator inside a string literal or substitution doesn't split. |
|
skills
Package skills owns spec-compliant Agent Skills: discovery, parsing, and the in-memory registry the agent loop reads.
|
Package skills owns spec-compliant Agent Skills: discovery, parsing, and the in-memory registry the agent loop reads. |
|
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`). |
|
syncutil
Package syncutil re-exports Mutex and RWMutex so the rest of the codebase can declare lock fields without caring whether a build wants the plain runtime primitives (this file, the default) or the instrumented ones from mutex_deadlock.go (`go test -tags deadlock`, `go run -tags deadlock`).
|
Package syncutil re-exports Mutex and RWMutex so the rest of the codebase can declare lock fields without caring whether a build wants the plain runtime primitives (this file, the default) or the instrumented ones from mutex_deadlock.go (`go test -tags deadlock`, `go run -tags deadlock`). |
|
trust
Folder trust — the per-directory consent gate that fires before the TUI opens a session in a previously-unseen workspace.
|
Folder trust — the per-directory consent gate that fires before the TUI opens a session in a previously-unseen workspace. |
|
tui/themes
Package themes is the palette registry the TUI's styles.go reads from when (re)building style vars.
|
Package themes is the palette registry the TUI's styles.go reads from when (re)building style vars. |
|
update
Package update polls GitHub once a day for newer yottacode releases and caches the answer under ~/.yottacode/cache/update-check.json.
|
Package update polls GitHub once a day for newer yottacode releases and caches the answer under ~/.yottacode/cache/update-check.json. |
|
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. |
|
worktree
Package worktree owns the git-worktree machinery yottacode layers on top of plain `git worktree`: name generation, path resolution under <repo>/.yottacode/worktrees/, .worktreeinclude file copying, and clean/dirty detection for end-of-session cleanup.
|
Package worktree owns the git-worktree machinery yottacode layers on top of plain `git worktree`: name generation, path resolution under <repo>/.yottacode/worktrees/, .worktreeinclude file copying, and clean/dirty detection for end-of-session cleanup. |
|
ychome
Package ychome resolves the root directory for yottacode's global state: $YOTTACODE_HOME when the override is set, ~/.yottacode otherwise.
|
Package ychome resolves the root directory for yottacode's global state: $YOTTACODE_HOME when the override is set, ~/.yottacode otherwise. |
Click to show internal directories.
Click to hide internal directories.