yottacode

yottacode is an autonomous, self-learning coding agent. Give it a goal in plain language and it plans the work, reads and edits real repositories, runs commands and tests, drives git, and iterates until the task is done — all from your terminal. It's model-agnostic by design: bring your own provider and swap models mid-session without changing how you work. As it goes, a self-learning memory layer captures what it discovers about you and your codebase and surfaces the most relevant pieces back into every turn, so it gets sharper the more you use it — while a built-in security policy of layered approvals and path validation gates every edit and shell command, keeping that autonomy under your control. Around the core loop you get an interactive terminal UI, a scriptable one-shot mode for automation, durable sessions, and cross-session recall.

Status: pre-1.0 (v0.3.0). The CLI, configuration, and on-disk formats are stabilizing. Pin a tag if you depend on yottacode from scripts.

Quick Start

One-liner install (Linux + macOS):

curl -fsSL https://raw.githubusercontent.com/yottadynamics/yottacode/main/install.sh | bash

Then launch the interactive setup wizard:

yottacode setup

Windows users should run yottacode under WSL.

export VERSION=0.3.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"

For build-from-source, cross-compilation, manual provider configuration, and other install paths, see docs/installation.md.

Why yottacode

• Memory that learns you. Memory is plain text and grep-able: you own USER.md, and the agent curates everything else through memory_save / memory_forget (project writes to YOTTACODE.md are approval-gated). A per-turn retrieval engine surfaces only what's relevant, so yottacode gets sharper about you and your codebase the more you use it. See docs/memory.md.

• Use any model, switch any time. Native adapters for OpenAI, Anthropic, Google Gemini, xAI (Grok), local Ollama (no API key), and ChatGPT OAuth, plus a generic OpenAI-compatible adapter for NVIDIA NIM, Groq, vLLM, Llama Stack, or any custom /v1 gateway. Swap provider or model mid-session with /provider use and /model — no lock-in, and no hidden default that silently bills you.

• A built-in security policy. A first-launch trust prompt scopes each workspace, mutating tools pause for approval with a syntax-highlighted diff, and project rules support allow / ask / deny (deny wins) for team-shared pre-approvals. Write-path validation confines edits to the working tree, blocks symlink writes, and firewalls secret-bearing paths (.env, ~/.ssh, cloud credentials) from both reads and writes. Tools run on the host with no in-process sandbox — containerize for stronger isolation. See docs/security-and-allow-lists.md.

• Deep GitHub integration. A typed go-github adapter (no shelling out to the gh CLI) gives the agent first-class pull-request and issue tools — read and review PRs, open and update them, post review comments, and triage issues — plus slash commands like /git-create-pr, /git-review-pr, and /git-implement-issue, which takes an issue end-to-end: research → plan → branch → implement → tests → commit → push → draft PR. See docs/github.md.

• A deep, repo-aware tool surface. Forty built-in tools span reads, writes, search, a full git suite (status / diff / blame / log / commit / checkpoint / rollback / file-at-revision), bash, tests, the todo_write working-plan tracker, and the plan-mode tools — each with an explicit approval policy. See docs/tools.md.

• Plan first, then let it run. Plan mode (/plan, Shift+Tab, or --permission-mode plan) investigates read-only and drafts a plan you approve; approving drops into auto mode so implementation skips per-tool prompts, while run_bash, git_commit, git_checkpoint, and rollback stay in the safety floor. Shift+Tab cycles normal → auto → plan mid-turn, and the agent can never escalate its own permissions.

• Delegate to typed subagents. Hand research, code search, planning, and verification to subagents that run in their own context window, so the parent only sees the final answer. Four ship built-in — Explore, Plan, general-purpose, and verification — and you can add your own under .yottacode/agents/.

• Reusable skills, loaded on demand. 17 built-in skill playbooks (SSH/remote ops, git investigation, TDD, security audit, code review, performance profiling, and more) load only when relevant, and you can install your own from a path, URL, or GitHub shorthand. Skills stay off until you enable them each session, following the agentskills.io spec.

• Undo any step. Every message is auto-checkpointed with the conversation and the pre-edit contents of the files about to change, so /checkpoints (or a double-tap of Esc) rolls back conversation, files, or both — with a configurable 30-day TTL.

• Never lose a session. Per-turn atomic saves survive crashed terminals, /recall runs local full-text search across every saved session, and /summarize compacts long histories after snapshotting the original transcript.

• Work in parallel. yottacode --worktree <name> runs a session in its own git worktree so two agents can edit the same repo without colliding, and a per-repo .worktreeinclude copies gitignored configs into each one. See docs/worktrees.md.

• Make it your own. Add /your-command by dropping a markdown file into ~/.yottacode/commands/ or .yottacode/commands/, with $ARGUMENTS substitution, optional frontmatter, and @<path> file references.

• Built for the terminal. Inline rendering keeps your scrollback intact, with markdown-rendered output, a Tab-completing slash palette, multi-line input, image paste, and a ? cheatsheet. Run it interactively, or script the same core in one-shot mode — yottacode run "…" puts the answer on stdout and reasoning on stderr — all from a single static Go binary.

Commands

Type / in the TUI to open the command palette — it filters as you type and supports Tab completion.

Auto mode and the permissions-bypass overlay are intentionally not slash commands: enter auto mode with Shift+Tab (or --permission-mode auto), and the bypass overlay only via yottacode --yolo at launch.

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

Documentation

Browse the full documentation online at yottacode.ai/docs. The guides below are the in-repo copies.

Contributing

yottacode is built in the open and contributions are very welcome — from typo fixes to new tools and provider adapters. The full guide lives in CONTRIBUTING.md; here's the short version.

Ways to contribute

• Report a bug or request a feature with the issue templates.
• Improve the docs — the in-repo docs/ guides or the published site at yottacode.ai/docs.
• Open a pull request for a fix or feature. Planning something big? File an issue first so we can align on the approach.

Before you open a PR

• Keep it focused — one logical change, with a clear description and the issue it closes (Closes #123).
• Ship code, tests, and docs together: every feature needs tests, every bug fix needs a regression test that fails before and passes after, and behavior changes update the matching docs/ guide.
• Make sure go test ./... and go vet ./... pass — CI runs build, vet, and tests on every PR and must be green before merge.

Where things plug in — adding a built-in tool, a slash command, or a model adapter is a well-defined seam; see the Development section and docs/development.md for build, test, and extension details.

Security and conduct — please don't file public issues for vulnerabilities. Use GitHub's "Report a vulnerability" button under the repository's Security tab, or follow the private reporting path in SECURITY.md. Community standards are in CODE_OF_CONDUCT.md.

Development

yottacode is a single, pure-Go binary (no CGo) 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
go test -race ./...              # race detector
go test -cover ./...             # coverage
go test -tags=integration ./...  # live-provider tests (needs API keys)

Where to extend — most feature work lands on a well-defined seam:

• A built-in tool — implement agent.Tool and register it in internal/tui/run.go and internal/oneshot/oneshot.go.
• A slash command — add an entry in internal/tui/commands.go.
• A provider adapter — extend internal/adapter; the agent loop depends only on the streaming interface.

See docs/development.md for the full guide — project layout, the model-catalog refresh, provider diagnostics, and release versioning.

License

MIT. See LICENSE.