autocomplete-rs

Fast, universal terminal autocomplete that works everywhere — without the positioning bugs.

Project Status: Early Development (Pre-Release)

autocomplete-rs is currently in active development. Core features are being implemented. Not yet ready for production use.

Why autocomplete-rs?

Frustrated with Kiro CLI (formerly Fig, then Amazon Q) and its persistent positioning bugs, I decided to build a better terminal autocomplete system from scratch.

The Problem with Kiro CLI (and its predecessors):

• Dropdown appears in the wrong location
• Breaks with multi-monitor setups
• Incorrect positioning in terminal multiplexers
• Issues with custom fonts and scaling
• Heavy resource usage (~100MB+ memory)

The autocomplete-rs Solution:

• Zero positioning bugs — Direct terminal control, no Accessibility API
• Blazing fast — <20ms total latency target
• Lightweight — <50MB memory, ~8-15MB binary
• Universal — Works on all terminals (iTerm2, Alacritty, Kitty, Ghostty, etc.)
• Built with Rust — Reliable, safe, and performant

Roadmap

Phase 1 — MVP (current)

• Daemon with Unix socket IPC
• Command buffer parser with tokenizer
• Inline ANSI completion dropdown
• Hardcoded git completion spec
• Zsh ZLE integration

Phase 2 — Scale

• Full Fig spec parsing (600+ CLI tools)
• MessagePack spec embedding
• LRU spec caching

Phase 3 — Polish

• Catppuccin theme support
• Configuration file system
• Theme customization

Phase 4 — Universal

• Bash support
• Fish support
• WSL support

See project issues (bd list) for detailed development plan.

Quick Start

Install

# Homebrew (macOS/Linux)
brew install jbabin91/tap/autocomplete-rs

# Cargo
cargo install autocomplete-rs

# Cargo binstall (pre-built binary)
cargo binstall autocomplete-rs

# Shell installer (macOS/Linux)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/jbabin91/autocomplete-rs/releases/latest/download/autocomplete-rs-installer.sh | sh

From Source

git clone https://github.com/jbabin91/autocomplete-rs.git
cd autocomplete-rs
cargo build --release
cp target/release/autocomplete-rs ~/.cargo/bin/

Requirements

• Rust: 1.85+ (Rust 2024 Edition)
• OS: macOS or Linux
• Shell: Zsh 5.8+ (Bash and Fish planned for Phase 4)
• Terminal: Any modern terminal emulator

How It Works

User types "git checkout " + Alt+Space
         |
+-------------------------+
|  ZLE Widget (zsh)       |  Captures buffer & cursor
+-------------------------+
         | Unix Socket (JSON)
+-------------------------+
|  Persistent Daemon      |  <10ms response time
|  +- Parser              |  Analyzes command context
|  +- Spec Matcher        |  Finds relevant completions
|  +- Response            |  Returns suggestions
+-------------------------+
         | JSON Response
+-------------------------+
|  Inline Dropdown        |  Renders below cursor
|  +- ANSI escape codes   |  No alternate screen
|  +- Keyboard navigation |  Arrow keys, Enter, Esc
+-------------------------+

Key Technical Decisions:

• Daemon Architecture — Persistent process for zero startup cost
• Direct Terminal Control — No Accessibility API, no positioning bugs
• Build-time Spec Parsing — Embed specs for instant availability

Development

# Install tools
mise install

# Common tasks
mise run build       # debug build
mise run release     # optimized build
mise run test        # cargo nextest run --all-features
mise run lint        # clippy
mise run fmt         # format all files
mise run ci          # fmt-check + check + lint + test

Git workflow: GitHub Flow with conventional commits. Squash or rebase merges only.

CI: GitHub Actions runs lint, test, and conventional commit checks on every push and PR.

See AGENTS.md for full development guidelines.

Project Structure

autocomplete-rs/
+-- src/
|   +-- main.rs          # CLI entry point (Clap)
|   +-- daemon/          # Tokio Unix socket server
|   +-- parser/          # Command buffer parsing (stub)
|   +-- (dropdown/)      # Inline ANSI dropdown (not yet implemented)
+-- shell-integration/
|   +-- zsh.zsh          # ZLE widget
+-- docs/                # Architecture docs, ADRs, guides
+-- .beads/              # Issue tracking
+-- .github/             # CI workflows, templates, actions

Contributing

Contributions welcome! This project is in early development and there's lots to do.

1. Read Contributing Guide
2. Check project issues (bd ready) for current priorities
3. Fork, branch (feat/, fix/, refactor/, chore/), and submit a PR
4. Use conventional commits

Inspiration & Related Projects

• Kiro CLI (formerly Fig/Amazon Q) — Original inspiration (and frustration)
• Fig Autocomplete Specs — 600+ completion specs we'll reuse
• Inshellisense — Microsoft's Node.js autocomplete
• Carapace — Go-based completion engine

Tech Stack

• Language: Rust 2024 Edition
• Dev Tools: mise (tool & task manager)
• Git Hooks: hk (with Rust builtins)
• Async Runtime: Tokio
• Terminal I/O: Crossterm (planned — inline ANSI dropdown)
• CLI: Clap (derive)

License

MIT License — see LICENSE file for details.