agentty

A blazing-fast, open-source coding agent in your terminal.
A drop-in Claude Code alternative in C++26 — one static binary, millisecond startup, any model.

agentty demo

## Why agentty? Most terminal coding agents ship as a Node or Python app and send big chunks of your repository to the model on every turn. agentty takes the opposite approach: - **It's one native binary.** 16.7 MB, ~3 ms cold start, zero runtime dependencies — no Node, no Python, no `npm install`, no `node_modules`. Download and run. - **It sends only the relevant code.** Built-in local retrieval (hybrid keyword + embedding search, code-aware chunking and ranking) fetches just the slices that matter — often cutting context by 80%+ vs. whole-repo dumping. - **It's not locked to one vendor.** Sign in with your Claude Pro/Max, or point it at OpenAI, Groq, OpenRouter, Cerebras, DeepSeek, xAI (Grok), Mistral, Gemini, Fireworks, or a fully local Ollama model. Switch live with `^P`. - **It's safe by default.** Shell and build commands run in a sandbox; air-gap an entire session over SSH with one command. - **It's open source (MIT)** and runs inside Zed over ACP. Coming from another tool? See the honest comparisons: [vs Claude Code](https://agentty.org/compare/agentty-vs-claude-code) · [vs Aider](https://agentty.org/compare/agentty-vs-aider) · [vs Cursor](https://agentty.org/compare/agentty-vs-cursor) · [all alternatives](https://agentty.org/alternatives). ## Getting Started ```bash curl -fsSL https://raw.githubusercontent.com/agentty-org/agentty/master/install.sh | sh cd your-project agentty ``` First launch opens auth — **paste an API key** (Anthropic `sk-ant-…`, or any provider's key) or use a local Ollama model that needs no key at all. You can also sign in with your Claude Pro/Max OAuth if you prefer. Once you're in, a first-run welcome card suggests a few things to try; just type and hit Enter. ## Features

### ⚡ Instant, all the way through Cold start under 1 ms; keystroke-to-pixel about 1 ms. No Node, no Python, no npm install — just a static binary. Independent tool calls run in parallel and read-only tools start while the model is still typing, so tool-heavy turns finish sooner. ### 🔌 Any model Claude, GPT, Groq, OpenRouter, Ollama, or any OpenAI-compatible endpoint. Switch live with `^P`. ### 🛡️ Sandboxed by default Every shell call runs inside an OS-enforced sandbox — claybin on Linux (seccomp + landlock + cgroup2; one engine, bwrap was removed), macOS (seatbelt + rlimits, with sandbox-exec as the fallback), and Windows (AppContainer + restricted token + job objects; there is no weaker fallback engine — when the host cannot build a wall, startup says so and commands run unconfined). Credential files are masked whether or not you configure anything, and file tools refuse paths outside your workspace. Deep dive: [`docs/SANDBOX.md`](docs/SANDBOX.md).

### 🌐 Air-gapped mode Run on a box with no internet. Your laptop relays the bytes over SSH with TLS pinned end-to-end. ### 🤖 Scripts and CI `agentty run "fix the failing test"` runs one prompt with tools and prints just the answer. `--json`, clear exit codes, `--timeout`, `--events jsonl` (tool calls and reasoning), and `--read-only --no-network` for untrusted code. [Docs ↗](https://agentty.org/docs/cli#agentty-run) ### 🔧 Full tool suite read · write · edit · bash · grep · glob · git · web · search_docs · search_code · task — each with a purpose-built widget. ### 🧠 Learns your codebase Agent Skills + remember/forget memory, plus a fully **local RAG** engine — hybrid keyword + embedding search with a code-aware reranker — over your code, docs, skills, and memory. Teach it once, every session knows your conventions. [How it works ↓](#retrieval-rag) ### 🎯 Smart Mode One flagship model plans; cheaper models do the legwork. Effort scales to each turn's complexity, a cascade retries harder only when a cheap attempt falls short, and the router **learns your repo** across sessions. Off is a strict no-op. [How it works ↓](#smart-mode)

## Providers ```bash agentty # bring your own key/model agentty --provider openai -m gpt-4o # GPT agentty --provider groq -m llama-3.3-70b # Groq agentty --provider ollama -m qwen2.5-coder # local model, no key agentty --provider openrouter # any model via OpenRouter agentty --provider deepseek -m deepseek-v4-pro # DeepSeek (DEEPSEEK_API_KEY) agentty --provider xai -m grok-4.6 # xAI Grok (XAI_API_KEY) agentty --provider gemini -m gemini-3.7-flash # Google Gemini (GEMINI_API_KEY) agentty -m claude-opus-4-5 # Claude (API key or Pro/Max OAuth) ``` `--provider` persists. Switch live in-app with `^P`. ## Retrieval (RAG) ### Retrieval without context dumping Rather than injecting a repository or every project document into each prompt, agentty retrieves a **small, source-tagged set of relevant passages** only when the task needs project knowledge. That keeps context focused, leaves more room for the task itself, and avoids paying to repeatedly send irrelevant material. agentty ships a **fully local retrieval engine** behind two tools. No cloud, no setup, works offline: keyword search works from the first run, and a local [Ollama](https://ollama.com) adds search by meaning. - **`search_code`** finds code by what it does ("where is retry backoff handled") when you don't know the name. The complement to `grep`. - **`search_docs`** searches your docs folder (`./docs`, or `AGENTTY_DOCS_DIR`), your installed skills, and facts you asked it to `remember`. Every returned passage is **source-tagged** (`docs:` · `skill:` · `memory:` · MCP URI) with its file + line range, so the model can cite, open, or follow it. **Turn on search by meaning** (one command): ```bash ollama pull qwen3-embedding:0.6b # or nomic-embed-text, smaller ``` agentty finds Ollama on localhost by itself and prefers `qwen3-embedding:0.6b` when it's there. `agentty diagnostics` shows whether it's on (`probe: ok`). The index is built once per repo and then updated only for files you change. On agentty's own judged questions, `search_code` puts the right file first 63-78% of the time with `qwen3-embedding` and in the top 8 93-97% (keyword only: 57-60% first, 92-95% top 8). Measure it on your repo with `agentty rag-eval`.

The retrieval funnel

Each search runs, in order: 1. **Structure-aware chunking** — code splits at functions and classes, docs at headings; each chunk is indexed with its title and heading path. 2. **Hybrid retrieval** — BM25 (keyword; identifiers split into words, so `onClipboardRead` matches "clipboard read") and dense embeddings (HNSW), fused per query. 3. **Rerank** — a deterministic feature reranker; for code, source ranks above tests and docs unless you ask for them, and a header lifts its `.cpp`. 4. **Diversify + de-duplicate** — MMR, near-duplicate removal, and stitching of adjacent chunks into one span. 5. **Compress + budget** — passages trimmed to the sentences that match the query and packed under a hard byte budget. 6. **Confidence** — each result carries a confidence; weak results say so. **Opt-in stages** (off by default; measure before turning on): pseudo-relevance feedback (`AGENTTY_RAG_PRF=1`), GraphRAG (`AGENTTY_RAG_GRAPH=1`), corrective retry (`AGENTTY_RAG_CORRECT=1`), and two that cost a model call: multi-query expansion (`AGENTTY_RAG_EXPAND=1`) and HyDE (`AGENTTY_RAG_HYDE=1`). **Proactive retrieval** (off until you turn it on in `/settings` → *Proactive retrieval (RAG)*) runs the funnel *before* the model asks and adds a source-tagged `` block to the turn, shown as one 📚 card with a confidence bar and the sources it used. All of it is in-house C++ ([rag-cpp](https://github.com/agentty-org/rag-cpp)), every stage degrades gracefully, and each is tunable via `AGENTTY_RAG_*`. Full write-up: [`docs/website/retrieval.md`](docs/website/retrieval.md).

## Smart Mode One model rarely fits every turn. A one-line rename and a cross-file refactor don't deserve the same effort, and burning flagship reasoning on trivia is just slow and expensive. Smart Mode (`^S`) fixes that with an **orchestrator-workers** design: a strong model owns the plan and delegates well-scoped subtasks to cheaper workers. It's built from **three roles** and **eight independent layers**, each a toggle: - **Strategic** (flagship) plans and delegates · **Implementation** (mid) writes code · **Utility** (cheap) handles summaries and grunt work. The resolver maps a *role* to `(model, effort)` — it never checks a model name by string, so pinning any model to any slot is always safe. - **Complexity-scaled effort** sizes each turn (trivial → complex), and a **cascade** retries at higher effort only when a cheap attempt actually falls short — the RouteLLM/cascade idea applied *inside* the agent loop. - Because the loop sees outcomes a stateless router can't — the build fails, the test goes red, you correct the next turn — Smart Mode **learns per-workspace**: it persists the effort prior the cascade discovered and recalls decompositions that worked. The second session in a repo is smarter than the first. All learning is local, on-disk (`.agentty/`), and wipeable. Open the overlay with `^S`; the footer shows what it's learned in this repo. **Off is a strict byte-for-byte no-op** — zero extra tokens, zero latency. Full write-up: [`docs/website/smart-mode.md`](docs/website/smart-mode.md). ## Keys | Key | Action | Key | Action | |-----|--------|-----|--------| | `Enter` | Send / queue | `^K` | Command palette | | `Esc` | Cancel / reject | `^J` | Thread list | | `S-Tab` | Cycle profile | `^P` | Provider picker | | `Alt+Enter` | Newline | `^/` | Model picker | | `^B` | Loop: resend until off | `^N` | New thread | | `^G` | Run code block | `^S` | Smart Mode | | `^R` | Review changes | `^T` | Plan / todo | | `^O` | Inspect tool outputs | `^E` | Expand composer | | `^C` | Quit (from anywhere) | | | | `^←/→` or `Alt+←/→` | Cycle threads | | | The composer is a full readline-style editor: | Key | Action | Key | Action | |-----|--------|-----|--------| | `^←/→` | Move by word | `^W` / `Alt+D` | Delete word back / forward | | `^U` / `Alt+K` | Kill to line start / end | `^Z` / `^Y` | Undo / redo | | `^V` / `Alt+V` | Paste image | `/` `@` `#` | Command / file / symbol picker | | `↑` | Recall queue / history | `Alt+↑/↓` | Edit queued messages one at a time | Full keymap: [docs/website/keybindings.md](docs/website/keybindings.md). Pasting images **over SSH** needs one terminal setting — see [Clipboard & Images](docs/website/clipboard.md). ## More

Installation options

**Linux** ```bash # Debian / Ubuntu (V = the release you want, e.g. 0.9.5) curl -fsSLO https://github.com/agentty-org/agentty/releases/latest/download/agentty_${V}_amd64.deb sudo dpkg -i agentty_${V}_amd64.deb # Fedora / RHEL / CentOS sudo dnf install https://github.com/agentty-org/agentty/releases/latest/download/agentty-${V}-1.x86_64.rpm # openSUSE sudo zypper install https://github.com/agentty-org/agentty/releases/latest/download/agentty-${V}-1.x86_64.rpm # Arch (AUR) yay -S agentty-bin # prebuilt static release yay -S agentty-git # build HEAD from source, dynamically linked # Alpine — no .apk yet; use the install script above ``` Package filenames carry the version, so `latest/download/` needs it spelled out — see the [releases page](https://github.com/agentty-org/agentty/releases/latest) for the exact names, or use the install script, which resolves it for you. **macOS** ```bash brew tap 1ay1/tap && brew install agentty ``` **Windows** ```powershell scoop bucket add 1ay1 https://github.com/1ay1/scoop-bucket; scoop install agentty # or winget install agentty.agentty ``` **Termux / Android** (no root, no proot) agentty builds natively against Termux's Bionic/libc++ toolchain. The install script detects Termux and installs into `$PREFIX/bin` (on your PATH): ```bash pkg install git cmake clang openssl libnghttp2 curl -fsSL https://raw.githubusercontent.com/agentty-org/agentty/master/install.sh | sh -s -- --build ``` Shell/build tools run **unsandboxed** on unrooted Android (Bubblewrap needs user namespaces Android doesn't grant) — everything else works. See [`packaging/termux/`](packaging/termux/) for the `pkg install agentty` recipe. **Anywhere (no package manager)** ```bash curl -fsSL https://raw.githubusercontent.com/agentty-org/agentty/master/install.sh | sh ``` If the prebuilt binary won't run on your system (e.g. a libc mismatch), pass `--build` to compile from source instead — the installer also does this automatically when the downloaded binary fails to execute: ```bash curl -fsSL https://raw.githubusercontent.com/agentty-org/agentty/master/install.sh | sh -s -- --build ``` **From source** (needs a C++26 toolchain — GCC 14+ / recent Clang / MSVC) ```bash git clone --recursive https://github.com/agentty-org/agentty.git cd agentty && cmake -B build && cmake --build build -j ``` **Named presets** (reproducible configs, no `-D` soup) — **use these if you are going to edit the code**: `debug` rebuilds in ~1.7 s after a one-line change vs ~36 s for the plain `cmake -B build` above, because it skips LTO. See [Building from source](https://agentty.org/docs/building#the-development-loop). ```bash cmake --preset debug && cmake --build --preset debug # fast Debug loop (no LTO, ccache) cmake --preset release && cmake --build --preset release # optimized -O3 + LTO binary ctest --preset debug # run the suite ``` Every preset shares one `build/` tree — switching preset reconfigures it in place instead of leaving a second multi-gigabyte copy on disk. `cmake --list-presets` shows them all (debug / debug-full / release / ci / sanitizer / standalone / pch). All binaries are a single fully-static executable (x86_64 + aarch64 on Linux, Intel + Apple Silicon on macOS; Termux/Android builds from source). Packaging details: [`packaging/README.md`](packaging/README.md).

Air-gapped hosts

```bash agentty airgap --setup user@host # first time: copies credentials agentty airgap user@host # every time after ``` Your laptop relays via SOCKS5-over-SSH. TLS pins on real upstreams — the network in between can't MITM you.

Inside Zed (ACP)

agentty speaks the [Agent Client Protocol](https://agentclientprotocol.com) — the same protocol Zed uses for Claude Code. Add to Zed's settings: ```json { "agent_servers": { "agentty": { "command": "agentty", "args": ["acp"] } } } ```

Loop a prompt until it's done (Ctrl+B)

Some prompts are worth sending more than once — *"fix the next failing test"*, *"keep refactoring until the build is clean"*, *"check if the deploy finished"*. `^B` sends the composer's message and then **re-sends it automatically after every completed turn**, until you press `^B` again. While armed, the composer keeps showing the prompt on repeat and becomes read-only (dimmed text, parked caret) — so the box can never say one thing while agentty sends another. A `⟳ LOOP ×N` chip and a tinted border make an auto-sending session impossible to mistake for an idle one, and the count makes it distinguishable from a hang. The model can't tell: an auto-sent turn goes through the same submit path as one you typed, with no marker on the wire, in the transcript, or in the saved thread. If a turn **fails**, the loop doesn't hammer the endpoint — re-sending a rate-limited turn instantly is how a 429 becomes a longer one. It waits: the provider's own `Retry-After` is obeyed verbatim when it sends one, otherwise the delay escalates per error class (rate-limit/auth from 30 s, transient blips from 5 s) and resets after the next success. The chip counts down (`⟳ RETRY 24s`) so a paused loop reads as waiting, not wedged. `Esc` cancels the turn; `^B` stops the loop.

Run code blocks from replies (Ctrl+G)

The AI hands you a fenced block of commands — don't copy-paste it. `^G` lists the blocks from the last reply; `Enter` (or a digit) runs one **interactively on your real terminal**: the TUI suspends, sudo password prompts work, output streams live, `Ctrl+C` kills the command (not agentty). When it exits, a result card lets you attach the captured output to the composer as a collapsed chip (`a`), copy it (`y`), or discard (`Esc`) — so "it failed with X" reaches the model without you re-typing anything. Runs the right shell per block on every OS: `sh`/`bash` blocks through `/bin/sh` on Linux/macOS, `powershell`/`pwsh` and `cmd`/`bat` blocks through PowerShell / `cmd.exe` on Windows. Prompt `$ ` markers are stripped, a block your platform can't run offers edit/copy instead, and capture is capped at 2 MB. Details: [`docs/RUN_CODE_BLOCK.md`](docs/RUN_CODE_BLOCK.md)

Agent Skills

Drop a `SKILL.md` anywhere under `.agentty/skills/` or `~/.agentty/skills/` — it's live next turn. Compatible with Claude Code's `.claude/skills/` format. A skill that runs programs or reaches the network says so in its frontmatter (`effects: [exec, net]`) and installs through `agentty skill add`, which shows you what it declared and pins the approval to the content — edit the body and it asks again. Prose-only skills are never gated. See [installing skills](docs/website/skill-install.md). The tier-1 catalog (name + description of every discovered skill) is capped at 64 entries. Set `AGENTTY_MAX_SKILLS` to override it (clamped to 8–4096) — lower it for small-context models, raise it for large skill libraries. On codebases with internal DSLs or tribal conventions, agent accuracy jumps from ~20% to ~85% with curated skills ([research](https://arxiv.org/abs/2410.03981)).

Architecture

Pure-functional update loop: `(Model, Msg) -> (Model, Cmd)`. View is `Model -> Element`, rendered by [maya](https://github.com/agentty-org/maya). Process management via `posix_spawn` + `poll(2)`. File writes are atomic (`write` + `fsync` + `rename`). Deep dive: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) · [`docs/RENDERING.md`](docs/RENDERING.md)

Releasing (maintainers)

Cutting a release is one command: ```bash scripts/cut-release.sh X.Y.Z # POSIX / macOS / Linux / Git-Bash scripts\cut-release.cmd X.Y.Z # Windows cmd.exe ``` It bumps `project(agentty VERSION …)` in `CMakeLists.txt` (the single source of truth every manifest derives from), promotes `CHANGELOG.md`'s `[Unreleased]` section to `[X.Y.Z]`, commits, tags `vX.Y.Z`, and pushes. The tag push fires GitHub Actions, which builds every binary + OS package (Linux x86_64/aarch64 on native runners, macOS Intel/ARM, Windows `.exe`/`.msi`) and auto-submits to winget, Homebrew, Scoop, and the AUR — nix/snap/gentoo manifests are attached to the release. `--dry-run` previews without writing anything.

## Community Join the [**Discord**](https://discord.gg/qhb9AZ8f3c) to ask questions, share sessions, and get help. The server has an AI helper bot that answers agentty questions using the real agent — `@mention` it, DM it, or use `/ask`. Prefer IRC? Come hang out in [**#agentty on Libera.Chat**](https://web.libera.chat/#agentty) (`irc.libera.chat`, port 6697, TLS). Matrix users can join `#agentty:libera.chat`. ## License MIT — see [LICENSE](LICENSE).