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.

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 source (needs a C++26 toolchain — GCC 14+ / recent Clang / MSVC)

git clone --recursive git@github.com:1ay1/agentty.git
cd agentty && cmake -B build && cmake --build build -j

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.

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.

agentty speaks the Agent Client Protocol — the same protocol Zed uses for Claude Code. Add to Zed's settings:

{
  "agent_servers": {
    "agentty": {
      "command": "agentty",
      "args": ["acp"]
    }
  }
}

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

Drop a SKILL.md anywhere under .agentty/skills/ or ~/.agentty/skills/ — it's live next turn. Compatible with Claude Code's .claude/skills/ format.

On codebases with internal DSLs or tribal conventions, agent accuracy jumps from ~20% to ~85% with curated skills (research).

Pure-functional update loop: (Model, Msg) -> (Model, Cmd). View is Model -> Element, rendered by maya. Process management via posix_spawn + poll(2). File writes are atomic (write + fsync + rename).

Deep dive: docs/ARCHITECTURE.md · docs/RENDERING.md

Cutting a release is one command:

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.