agentty

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 retrieval (hybrid BM25 + dense embeddings, code-aware chunking, GraphRAG) 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 · vs Aider · vs Cursor · all alternatives.

Getting Started

curl -fsSL https://raw.githubusercontent.com/1ay1/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 both Linux (seccomp + landlock + cgroup2, with bubblewrap as the fallback) and macOS (seatbelt + rlimits, with sandbox-exec as the fallback). Credential files are masked whether or not you configure anything, and file tools refuse paths outside your workspace. Deep dive: 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 ↗

🔧 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 BM25 + embeddings, RRF-fused, reranked, diversified, and expanded over a GraphRAG document graph — over your docs, skills, and memory. Teach it once, every session knows your conventions. How it works ↓

🎯 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 ↓

Providers

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 complete, fully-local retrieval engine behind two tools — no cloud, no dependencies, works offline. The only optional network hop is a localhost Ollama server for embeddings; with none reachable it falls back to keyword search and keeps working.

• search_docs — searches your knowledge base: a docs folder, your installed skills, your learned remember memory, and (opt-in) connected MCP resources. Useful from the first turn — skills and memory are always indexed, even with no docs folder.
• search_code — semantic search over your source by meaning, for "where is retry backoff handled" questions where you don't know the identifier. The hybrid complement to grep.

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.

Enable the semantic half (BM25 works with zero setup):

ollama pull nomic-embed-text && ollama serve     # localhost embeddings
export AGENTTY_DOCS_DIR=~/my-project/docs         # optional; skills+memory always indexed

agentty auto-detects the running server and upgrades from BM25-only to full hybrid retrieval — no restart needed.

Every search_docs call runs this pipeline. The default path makes no LLM calls — it's fast, deterministic, and safe to leave fully on.

1. Hybrid retrieval — BM25 (keyword, Porter-stemmed) and dense embeddings (HNSW-indexed at scale) each rank a wide candidate pool; the two lists are fused with Reciprocal Rank Fusion (or opt-in Relative Score Fusion, AGENTTY_RAG_FUSION=rsf). Every dense probe a search fans out — expansion, HyDE, multi-hop — embeds in one batched round-trip, not one per probe.
2. Pseudo-relevance feedback (RM3) — harvests discriminative terms from the top hits and fuses a second down-weighted probe, recovering the vocabulary you didn't type. Sub-millisecond, no model.
3. Contextual retrieval — each chunk is indexed with a breadcrumb of its doc title + heading path, so guide.md › Install › Linux is findable even when the body never says "linux".
4. Re-ranking — a deterministic feature-fusion reranker (term coverage, phrase proximity, title match, calibrated cosine), plus an optional batched embedding cross-encoder and an opt-in generative 0–10 judge.
5. MMR diversification — greedily keeps hits that are relevant and distinct, so duplicate windows don't crowd out real answers.
6. Compression — trims each survivor to its best query-relevant span: "20k noisy tokens" → "2k useful tokens."
7. Parent-document expansion — stitches the precise hit back into its adjacent sibling chunks so the model reads it in context.
8. GraphRAG expansion — builds the corpus's document graph (nodes = docs; edges = markdown links + tf·idf entity co-occurrence), runs PageRank and community detection over it, and pulls in supporting docs from four tiers around the top hits (outbound links, backlinks, entity neighbours, and the community hub). Deterministic, in-memory, no model.
9. Corrective retry (CRAG) — on a low-confidence result, de-noises the query, widens the pool, and keeps whichever attempt scored higher.

Opt-in recall boosters (cost a model call, off by default): RAG-Fusion query expansion (AGENTTY_RAG_EXPAND=1), HyDE hypothetical-document embeddings (AGENTTY_RAG_HYDE=1), and GraphRAG community summaries (AGENTTY_RAG_GRAPH_SUMMARY=1 — a cached natural-language report per topic cluster, generated