agentty

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 startup

Cold start under 1ms. No Node, no Python, no npm install. Just a static binary.

🔌 Any model

Claude, GPT, Groq, OpenRouter, Ollama, or any OpenAI-compatible endpoint. Switch live with ^P.

🛡️ Sandboxed by default

Every shell call runs inside bwrap (Linux) / sandbox-exec (macOS). File tools refuse paths outside your workspace.

🌐 Air-gapped mode

Run on a box with no internet. Your laptop relays the bytes over SSH with TLS pinned end-to-end.

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

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 -m claude-opus-4-5                 # Claude (API key or Pro/Max OAuth)

--provider persists. Switch live in-app with ^P.

Retrieval (RAG)

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 once per corpus shape).

Beyond the explicit tool, a proactive path runs the funnel before you ask when your message looks knowledge-shaped, injecting a source-tagged <retrieved-context> block into the very same turn — grounding without a tool round-trip. The transcript renders it as one quiet 📚 card that shows a confidence bar plus exactly which sources grounded the answer (docs · path, skill · name, memory…) and a passage count, so you can always see — and weigh — what the model was standing on.

BM25, RRF, HNSW, the reranker, MMR, compression, PRF, the chunker, and the GraphRAG document graph (PageRank, entity extraction, community detection) are all in-house C++/STL. Every stage degrades gracefully and is tunable via AGENTTY_RAG_* env vars. For big corpora, two opt-in vector-cost levers keep the ANN cheap while the full-precision rerank recovers quality: Matryoshka dimension truncation (AGENTTY_RAG_ANN_DIM=256, ~2.3× faster walk) and binary quantization (AGENTTY_RAG_BINARY=1, popcount-Hamming walk + float rescore, ~2.5×). Full write-up: docs/website/retrieval.md.

Keys

More

Linux

# Debian / Ubuntu
curl -fsSLO https://github.com/1ay1/agentty/releases/latest/download/agentty_amd64.deb
sudo dpkg -i agentty_amd64.deb

# Fedora / RHEL / CentOS
sudo dnf install https://github.com/1ay1/agentty/releases/latest/download/agentty-x86_64.rpm

# openSUSE
sudo zypper install https://github.com/1ay1/agentty/releases/latest/download/agentty-x86_64.rpm

# Arch (AUR)
yay -S agentty-bin

# Alpine
curl -fsSLO https://github.com/1ay1/agentty/releases/latest/download/agentty-x86_64.apk
sudo apk add --allow-untrusted agentty-x86_64.apk

macOS

brew tap 1ay1/tap && brew install agentty

Windows

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):

pkg install git cmake clang openssl libnghttp2
curl -fsSL https://raw.githubusercontent.com/1ay1/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/ for the pkg install agentty recipe.

Anywhere (no package manager)

curl -fsSL https://raw.githubusercontent.com/1ay1/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:

curl -fsSL https://raw.githubusercontent.com/1ay1/agentty/master/install.sh | sh -s -- --build

**From so