agentty
AI pair programming in your terminal: one static binary, sub-ms startup, any model, with local RAG that sends only the relevant code.
The README claims shells run sandboxed by default (bwrap/sandbox-exec), file tools refuse paths outside the workspace, retrieval results are source-tagged (docs:/skill:/memory:), air-gap mode pins TLS, and file writes are atomic; CI workflows scope permissions to contents:read and enforce a repo allowlist for Discord forwarding. However, this review sees only README, LICENSE, and CI config — no implementation code to verify any of these safety claims — so least_privilege, user_confirmation, data_flow_transparency, sensitive_data_handling, external_effects, and rollback each score 1 (asserted without support). source_attribution scores 2: the MIT license is complete and attributed. dependency_security scores 1: SHA-pinned submodules and vcpkg give some reproducibility, but no dependency manifest, version lockfile, or vulnerability-scanning evidence is present.
The README is internally consistent and CI includes Linux build+test, ASan/UBSan, two Windows toolchains, and fuzz smoke gates, with concrete retry descriptions (Retry-After, error-class backoff), so self_consistency scores 2. dependency_availability scores 1: the BM25 fallback when Ollama is unreachable is a claim, not verifiable evidence. failure_messages scores 1: backoff and loop countdown chips are described, but the quality of error presentation cannot be confirmed from static files.
Audience and scenario coverage is strong (Linux/macOS/Windows/Termux/Zed/air-gap/multi-provider); the Termux unsandboxed limitation is explicitly stated and the MSVC/MinGW toolchain blind spots are candidly noted in CI comments, so audience_and_scenarios, capability_boundaries, and environment_fit each score 2. trigger_precision scores 1: proactive retrieval fires on a 'message looks knowledge-shaped' heuristic with undefined boundaries.
The README is well structured with a coherent docs link system (architecture/rendering/keybindings/building), so information_architecture scores 2; installation docs cover multiple package managers, source builds, CMake presets, and fallback behavior, scoring 2. known_limitations scores 2: Termux unsandboxed and MSVC constraints are stated. license scores 3: a complete, standard MIT file. Elsewhere: naming_stability scores 1 (env vars and keymaps are documented but no stability commitment); examples_and_faq scores 1 (examples, no FAQ); versioning_changelog scores 1 (cut-release scripts and CHANGELOG references but no actual changelog shown); maintenance_responsibility scores 1: a single named author with a Discord community, and the CI comment about phantom required checks hints at process friction, with no explicit maintainer commitment.
output_usability scores 1: tool output cards, collapsible chips, and ^O inspection are described but unverifiable without code. marginal_value scores 1: the differentiation vs Node-based agents (local RAG, Smart Mode, static binary) is clear, but quantified claims ('80%+ context reduction') lack evidence. cost_benefit scores 1: Smart Mode's cost savings are asserted with no data.
claim_traceability scores 1: docs files and one arXiv paper are cited, but performance figures (~3ms, ~20%→85% accuracy) have no traceable source. cross_source_corroboration scores 1: CI config partially corroborates the existence of testing and packaging, but core functional claims (sandbox, RAG pipeline) have no second source. fact_inference_separation scores 1: the README mixes marketing language with technical facts ('honest comparisons' is an evaluation, not a fact) without distinction.
- Sandboxing, path restrictions, and data-flow claims come solely from the README; no implementation code was available in this static review — verify the actual sandbox coverage before relying on them.
- The install script uses a curl | sh pattern and the publisher is unverified; review the script content before executing it.
- Performance and accuracy figures (~3ms startup, 80%+ context reduction, 20%→85% accuracy) have no verifiable source and should not drive adoption decisions.
- Shell commands explicitly run unsandboxed on Termux/Android; avoid using the bash tool on that platform in sensitive environments.
- Smart Mode's local learning persists to the .agentty/ directory; mind workspace data isolation on shared or multi-user machines.
What does this agent do, and when should you use it?
agentty (GitHub: 1ay1/agentty) is an open-source terminal coding agent written in C++26, positioned as a Claude Code alternative and released under the MIT license. It ships as a single fully static native binary (~16.7 MB) with ~3 ms cold start and no Node, Python, or runtime dependencies. It embeds a fully local retrieval engine — hybrid BM25 plus dense embeddings with HNSW indexing, RRF fusion, reranking, MMR diversification, GraphRAG document-graph expansion, and CRAG corrective retry — exposed through the search_docs and search_code tools to fetch only relevant slices, which the README claims cuts context by 80%+ versus whole-repo dumping. It is vendor-agnostic on the model side: Anthropic (including Claude Pro/Max OAuth), OpenAI, Groq, OpenRouter, Cerebras, DeepSeek, xAI, Mistral, Gemini, Fireworks, and local Ollama are all supported, switchable live with ^P. Security is default-on: shell and build commands run in a bwrap (Linux) / sandbox-exec (macOS) sandbox, file tools refuse paths outside the workspace, and an air-gapped mode relays sessions over SSH. It also speaks the Agent Client Protocol, so it runs inside the Zed editor as an agent server.
Accepts natural-language tasks in a terminal TUI, calls LLMs, and drives a full tool suite — read, write, edit, bash, grep, glob, git, web, search_docs, search_code, task — each with a purpose-built widget. It reads workspace files and docs, executes shell/build commands inside a sandbox, produces and applies code edits, and lets you review changes with ^R. search_docs runs a nine-stage retrieval funnel over your knowledge base (docs folder, installed skills, remember memory, and opt-in MCP resources); search_code performs semantic search over source, complementing keyword grep. Smart Mode (^S) uses an orchestrator-workers design: a flagship model plans and delegates to cheaper workers, effort scales to per-turn complexity with a cascade retry, and it learns per-workspace with local state persisted under .agentty/. It supports Agent Skills (SKILL.md, compatible with Claude Code's .claude/skills/ format), MCP, ^B prompt looping, ^G interactive execution of code blocks from replies on your real terminal, and the agentty airgap command to serve internet-less hosts via SSH relay.
- Developers on air-gapped or restricted machines: run agentty airgap user@host so a laptop relays model access over SSH with TLS pinning to an offline box.
- Privacy-sensitive local-first users: run fully offline with --provider ollama -m qwen2.5-coder and no API key at all.
- Existing Claude Pro/Max subscribers: sign in with OAuth and reuse the subscription instead of buying separate API credits.
- Engineers on large, sparsely documented codebases: use search_code semantic queries (e.g. 'where is retry backoff handled') and GraphRAG-augmented retrieval to locate code without whole-repo context dumping.
- Cost-conscious teams: enable Smart Mode so a flagship model plans while cheaper models do the legwork, with the cascade escalating effort only on failure.
- Zed editor users: plug agentty in over ACP (agentty acp) as an agent server.
- Android/Termux users: native build installs into $PREFIX/bin without root or proot (though sandboxing is unavailable on unrooted Android).
What are this agent's strengths and limitations?
- A single 16.7 MB static binary with ~3 ms cold start and zero runtime dependencies — download and run — a concrete differentiator versus typical Node/Python terminal agents.
- Fully local RAG (BM25+dense, RRF, GraphRAG, CRAG) fetches only relevant passages; README claims 80%+ context savings vs whole-repo dumping, and it works offline (BM25 fallback without Ollama).
- Model/vendor agnostic: Anthropic (including Pro/Max OAuth), OpenAI, Groq, DeepSeek, xAI, Gemini, Ollama and more, with live ^P switching — no vendor lock-in.
- Safe by default: shell commands run in bwrap/sandbox-exec sandboxes, file tools are workspace-confined, plus an SSH air-gap mode.
- Smart Mode's orchestrator-workers design scales model/effort to turn complexity and learns per-workspace locally; off is a strict byte-for-byte no-op.
- Building from source requires a C++26 toolchain (GCC 14+ etc.) — a higher bar than Node/Python projects; code edits need the debug preset or a full rebuild takes ~36 s.
- Semantic retrieval (dense embeddings, HyDE, GraphRAG summaries) depends on a local Ollama embedding server or extra model calls; only BM25 is zero-setup.
- On unrooted Android/Termux, shell and build tools run unsandboxed (Android doesn't grant user namespaces), degrading the security model on that platform.
- Opt-in recall boosters (RAG-Fusion, HyDE, GraphRAG community summaries) are off by default and each costs a model call, adding latency and cost when enabled.
- Against mature rivals like Claude Code, Aider, and Cursor, real-world ecosystem maturity lacks independent evidence beyond README claims — evaluate with your own workloads before migrating.
How do you install or deploy this agent?
One-line install: curl -fsSL https://raw.githubusercontent.com/1ay1/agentty/master/install.sh | sh. Package managers — Debian/Ubuntu: download agentty_amd64.deb and sudo dpkg -i; Fedora/RHEL: sudo dnf install <release URL for agentty-x86_64.rpm>; Arch: yay -S agentty-bin; macOS: brew tap 1ay1/tap && brew install agentty; Windows: scoop bucket add 1ay1 ... ; scoop install agentty, or winget install agentty.agentty. If the prebuilt binary won't run (e.g. libc mismatch), build from source with curl -fsSL ... | sh -s -- --build (requires a C++26 toolchain: GCC 14+ / recent Clang / MSVC); developers should use cmake --preset debug for a fast iteration loop.
How do you use this agent?
Run cd your-project && agentty. First launch opens auth: paste an API key (Anthropic sk-ant-… or any provider's key), sign in with Claude Pro/Max OAuth, or pick a local Ollama model (no key needed). Examples: agentty --provider openai -m gpt-4o, agentty --provider groq -m llama-3.3-70b, agentty --provider ollama -m qwen2.5-coder. --provider persists; ^P switches providers live, ^S toggles Smart Mode, ^B loops a prompt, ^G runs code blocks from replies, ^R reviews changes, ^K opens the command palette. To enable semantic retrieval: ollama pull nomic-embed-text && ollama serve, optionally export AGENTTY_DOCS_DIR=~/my-project/docs; drop SKILL.md files under .agentty/skills/ or ~/.agentty/skills/. For Zed, configure an agent_server with command agentty and args ["acp"].