# agentty: a C++26 coding agent that ships as one static binary

> agentty is a terminal coding agent written in C++26 and distributed as a single static binary with local hybrid retrieval. It targets engineers who want a Claude Code style workflow without a Node or Python runtime, and who are willing to trade ecosystem breadth for that.

**1ay1/agentty** — AI pair programming in your terminal — one static binary, sub-ms startup, any model

- Repository: https://github.com/1ay1/agentty
- Website: https://agentty.org
- Stars: 615 · Forks: 24
- Language: C++
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/1ay1-agentty

## The problem agentty is aimed at

Most terminal coding agents are distributed as Node or Python applications. That means a runtime, a package manager, and a dependency tree before the first prompt. The agentty README frames its own position against that: it describes the project as one native binary, 16.7 MB, with roughly 3 ms cold start and zero runtime dependencies. Whether or not those numbers hold on your hardware, the packaging choice is the point. There is no npm install step, no node_modules directory, and no interpreter to keep patched.

The second problem the project names is context. The README argues that many agents send large chunks of a repository to the model on every turn, and that agentty instead retrieves a small, source-tagged set of relevant passages only when a task needs project knowledge. The README claims this often cuts context by more than 80 percent compared with whole-repo dumping. That figure comes from the project, not from an independent measurement, so treat it as a design goal rather than a benchmark.

The audience is narrow and clear. This is for engineers who already work in a terminal, already have an API key or a local model, and care more about startup latency and runtime footprint than about a marketplace of extensions.

## How the retrieval engine actually works

agentty exposes retrieval through two tools rather than one search box. search_docs searches a knowledge base made of a docs folder, installed skills, learned memory, and opt-in connected MCP resources. search_code is described as semantic search over source code, meant for questions like where retry backoff is handled, when you do not know the identifier to grep for. The README positions search_code as the hybrid complement to grep, not a replacement.

The pipeline is hybrid BM25 plus dense embeddings, fused with reciprocal rank fusion, then reranked, diversified, and expanded over a GraphRAG document graph. The README states the default path makes no LLM calls. That matters: retrieval quality does not depend on a model round trip, and the cost of a search is local compute.

Every returned passage is source-tagged with a prefix such as docs:, skill:, memory:, or an MCP URI, along with its file and line range. That tagging is what lets the model cite or open the passage instead of paraphrasing it. The design assumes the model will follow references, which is a reasonable bet for the tool-calling models the project targets.

The engine is local. The only optional network hop the README mentions is a localhost Ollama server used for embeddings. If none is reachable, retrieval falls back to keyword search and keeps working. That fallback is the strongest part of the design, because it means a missing embedding server degrades quality rather than breaking the tool.

## Installing agentty and running a first session

The README gives a single install command that pipes a shell script into sh. It fetches install.sh from the master branch of the repository. You should read that script before running it, as with any curl-to-shell installer.

```bash
curl -fsSL https://raw.githubusercontent.com/1ay1/agentty/master/install.sh | sh
cd your-project
agentty
```

On first launch the README says an auth screen opens. You can paste an API key, for example an Anthropic key beginning with sk-ant-, or any other provider's key, or use a local Ollama model that needs no key. Claude Pro or Max OAuth sign-in is also offered. After authentication, a first-run welcome card suggests a few things to try.

To use a local model instead of a hosted one, pass the provider and model explicitly. The README gives this example for Ollama with a coder model.

```bash
agentty --provider ollama -m qwen2.5-coder
```

The README notes that --provider persists, so you do not repeat it every session. You can also switch provider live inside the app with the ^P key binding. Other documented examples include --provider openai with -m gpt-4o, --provider groq with -m llama-3.3-70b, and --provider deepseek with -m deepseek-v4-pro, which reads the DEEPSEEK_API_KEY environment variable.

Retrieval works with zero setup in BM25-only mode. To enable the semantic half, the README gives two steps: pull an embedding model and serve it, then optionally point agentty at a docs folder.

```bash
ollama pull nomic-embed-text && ollama serve
export AGENTTY_DOCS_DIR=~/my-project/docs
```

The README states that agentty auto-detects the running server and upgrades from BM25-only to full hybrid retrieval without a restart. Skills and memory are always indexed, so the docs directory is optional.

## Sandboxing, air-gapped mode, and what they do not cover

The README states that every shell call runs inside bwrap on Linux or sandbox-exec on macOS, and that file tools refuse paths outside your workspace. This is the safety story, and it is a real architectural decision rather than a prompt-level instruction. It also has a dependency the README does not dwell on: bwrap and sandbox-exec are external programs. If bwrap is not installed on a Linux host, the sandbox described here has nothing to run inside. The README does not document what happens in that case, so verify it on your distribution before trusting the default.

The air-gapped mode is more unusual. The README describes running agentty on a machine with no internet, with your laptop relaying bytes over SSH and TLS pinned end to end. That is a genuine deployment shape for restricted environments, and it is the feature least likely to have an equivalent in a Node-based agent, because those typically assume outbound HTTPS from the same process.

What the README does not cover is equally worth noting. There is no documented rollback for the retrieval index, no description of how the learned memory or the Smart Mode router state is stored, and no stated size limit for the docs folder you point AGENTTY_DOCS_DIR at. If you plan to index a large monorepo, that last omission is the one to test first.

## Smart Mode and the multi-provider router

Smart Mode is the project's cost-control mechanism. The README describes it as one flagship model doing the planning while cheaper models do the legwork, with effort scaling to each turn's complexity. A cascade retries harder only when a cheap attempt falls short, and the router learns your repository across sessions. The README states that turning Smart Mode off is a strict no-op, meaning no routing decisions are made and no state is written.

That last detail is the important one. A cost-saving router that changes behaviour when disabled is a liability, and a strict no-op is the correct contract. It also means you can compare a routed session against a direct one without worrying that the comparison is contaminated.

Provider coverage is broad by design. The README lists Claude, GPT, Groq, OpenRouter, Ollama, DeepSeek, xAI, Gemini, Fireworks, Cerebras, and any OpenAI-compatible endpoint. The practical benefit is that you can start on a hosted flagship for planning and move routine work to a local Ollama model without changing tools. The practical cost is that behaviour will differ across providers, and the README does not claim otherwise. Tool-calling reliability in particular is a property of the model, not of agentty, so a model that handles the read, write, edit, bash, grep, glob, git, web, search_docs, search_code, and task tools poorly will produce a poor session regardless of the agent's own quality.

## Where agentty is the wrong tool, and what to use instead

agentty is the wrong choice if your team's workflow depends on an editor-integrated agent with a graphical diff review, or on a plugin ecosystem. The README mentions running inside Zed over ACP, which is a real integration, but it is one editor and one protocol. If your organisation standardised on a different editor's agent panel, agentty does not meet you there.

Aider is the honest comparison to make, and the project itself links a comparison page. The difference in approach is retrieval. Aider's model is built around editing files you name, with a repo map to help the model find its way. agentty instead invests in a local hybrid retrieval engine with embeddings, rank fusion, reranking, and a document graph, and exposes it through search_docs and search_code. If your sessions are mostly "change this function I am pointing at", the retrieval machinery is overhead you pay for in binary size and configuration. If your sessions are mostly "where in this codebase is this handled", the retrieval engine is the reason to pick agentty over a file-oriented editor.

The second difference is runtime. Aider is a Python application. agentty is a compiled binary. If you deploy agents into containers or onto machines where you cannot install an interpreter, that distinction decides the choice on its own. If you need to read and modify the agent's own source to fix a bug, Python is the easier target, and a C++26 codebase raises that bar considerably.

## Maintenance, licence, and upgrade cost

The repository is not archived, and the last push was on 2026-09-10. Three releases landed in the two weeks before that: v0.6.0 on 2026-09-02, v0.7.0 on 2026-09-04, and v0.8.0 later the same day. That cadence is fast, and fast cadences have a cost. At 0.x version numbers, config keys, environment variables, and CLI flags can move between releases. The README documents AGENTTY_DOCS_DIR as an environment variable and describes --provider as persisting, but it does not promise stability for either. Pin a version if you script around them.

The licence is MIT, which is permissive and imposes essentially no conditions beyond retaining the notice. For most commercial use that is the least friction available. This is a description of the licence text, not legal advice; if your organisation has a policy on copyleft or on bundled third-party code, check the dependency licences yourself, because the repository layout includes vendored directories such as acp-cpp, mcp-cpp, rag-cpp, and maya whose terms are not stated in the README.

The upgrade path is a re-run of the install script or a download of the latest release binary. Because the binary is static and has no runtime dependencies, upgrading does not involve a dependency resolution step. That is a genuine operational advantage over a Python or Node agent, where an upgrade can drag in transitive changes you did not ask for.

## Conclusion

Adopt agentty if you want a terminal coding agent with no Node or Python runtime, a local retrieval engine, and per-provider model choice, and if you are comfortable verifying sandbox behaviour on your own platform first. Do not adopt it if you need a large plugin ecosystem, a long track record, or a documented rollback path for its retrieval index; the README does not describe one. Before committing, install it on a scratch checkout, run the retrieval upgrade steps with a local Ollama server, and confirm that bwrap or sandbox-exec is actually available on your machine, because the sandbox claim depends on those binaries being present.

## FAQ

### What is agentty?

agentty is an open source coding agent that runs in the terminal, written in C++26 and distributed as a single static binary under the MIT licence. It supports multiple model providers and includes a local retrieval engine for searching your docs and source code.

### How do I install agentty?

The README gives a single command that pipes install.sh from the repository's master branch into sh, after which you run agentty from inside your project directory. As with any curl-to-shell installer, read the script before executing it.

### Does agentty require an API key?

It does not. The first launch screen accepts a pasted API key from any supported provider or a Claude Pro or Max OAuth sign-in, but the README also documents using a local Ollama model that needs no key at all.

### Can agentty run without internet access?

The README describes an air-gapped mode where agentty runs on a machine with no internet and your laptop relays the bytes over SSH with TLS pinned end to end. Retrieval is local as well, with an optional localhost Ollama server for embeddings.

## Sources

- [1ay1/agentty on GitHub](https://github.com/1ay1/agentty)
- [License: MIT](https://github.com/1ay1/agentty/blob/master/LICENSE)
- [Project website](https://agentty.org)
- [README](https://github.com/1ay1/agentty/blob/master/README.md)
- [Releases](https://github.com/1ay1/agentty/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/1ay1-agentty