Show HN: Namo_complete: a non-obtrusive AI autocomplete for the bash terminal
**namo_complete** is an open-source bash completion tool that provides AI-powered command suggestions using Claude's API, running entirely locally on Linux The architecture uses three processes: a thin bash shell handler, a daemon for AI inference and caching, and an output relay that intercepts terminal I/O via pseudo-terminals (PTYs) Key interaction model: users type normally, and after a brief pause (default 0.2s debounce), a dim hint appears below the current line; press Alt-O to accept, Alt
Analysis
TL;DR
- namo_complete is an open-source bash completion tool that provides AI-powered command suggestions using Claude's API, running entirely locally on Linux
- The architecture uses three processes: a thin bash shell handler, a daemon for AI inference and caching, and an output relay that intercepts terminal I/O via pseudo-terminals (PTYs)
- Key interaction model: users type normally, and after a brief pause (default 0.2s debounce), a dim hint appears below the current line; press Alt-O to accept, Alt-A to see candidates, or Alt-G for plain-English command description mode
- Privacy-conscious by design: API keys matching patterns like
sk-,ghp_,AKIAare stripped from history before requests; sensitive users can disable history entirely withNAMO_HISTORY_LINES=0 - Responses are cached locally in
~/.cache/namo_complete/keyed by typed text, directory, and model, with a 900-second TTL, reducing API costs and latency for repeated commands
Why It Matters
This represents a practical application of LLM-powered shell assistance that prioritizes privacy and local execution over cloud-dependent solutions, addressing a growing concern among developers about sensitive command history being sent to external APIs. The PTY-based architecture that intercepts output without modifying the shell's core behavior is an elegant engineering approach that could influence future CLI tooling designs.
Technical Details
- Architecture: Three-process design using named pipes for inter-process communication; the daemon handles all AI logic while the output relay captures terminal output via a pseudo-terminal pair, preserving the shell's native line editor for input handling
- Model: Defaults to
claude-haiku-4-5via the Anthropic Messages API, but supports any Claude model through theNAMO_MODELenvironment variable; requiresANTHROPIC_API_KEY - Context window: Sends the current typed line, last 10 lines of command output, current directory path, up to 40 filenames, and up to 50 recent shell history commands; all configurable via environment variables
- Key bindings:
Alt-Oaccepts the top hint,Alt-Alists alternative candidates with numeric selection,Alt-Gentersask>mode for natural language command description - Security: Regex-based detection and stripping of known API key patterns (
sk-,ghp_,github_pat_,AKIA,xoxb-,xoxp-) before request construction; complete history disable option available
Industry Insight
- The growing trend of AI-assisted CLI tools should prioritize local-first architectures with explicit privacy controls, as developers increasingly handle sensitive credentials and proprietary commands in their shells
- The PTY interception pattern demonstrated here offers a non-invasive way to augment terminal experiences without forking or replacing existing shell ecosystems, making it a viable model for future terminal enhancement tools
- Caching AI-generated completions locally by input context is a cost-effective strategy that also improves response times; this pattern could be adopted by other AI-CLI integrations to reduce API spend while maintaining responsiveness
Disclaimer: The above content is generated by AI and is for reference only.