agentty

AI pair programming in your terminal
One static binary. Sub-millisecond startup. Any model.

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)

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.

The retrieval funnel

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

Key	Action	Key	Action
Enter	Send	^K	Command palette
Esc	Cancel / reject	^J	Thread list
S-Tab	Cycle profile	^P	Model picker
Alt+Enter	Newline	^N	New thread
^G	Run code block	^←/→ or Alt+←/→	Cycle threads

More

Installation options

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.

Air-gapped hosts

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 — the same protocol Zed uses for Claude Code. Add to Zed's settings:

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

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

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.

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

Architecture

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

Releasing (maintainers)

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.

License

MIT — see LICENSE.