A few months ago, I started building smart-terminal. Initially, it was just meant to be a modest portfolio project—a way to build something cool with Rust and explore how LLMs could fit into a developer's daily workflow.
Along the way, it became much more than that. It became my playground for learning AI agentic concepts from first principles (ReAct loops, action spaces, tool execution engines, and multi-turn planning). More importantly, it turned into a tool I actually use in my own terminal every day. It is not a crazy, over-engineered solution, but it works, it is robust, and it was shaped by months of my own iterations and real daily use.
Now that I'm about to step away from active development on it, I wanted to document how it evolved, the architectural dead-ends I hit, and why anyone interested is welcome to pick it up or contribute.
The initial mistake: Trying to wrap the terminal (PTY)
When I started in January, my first instinct was to build a full terminal wrapper.
The idea on paper was:
- Spawn a subshell (
bash) usingportable-pty. - Intercept raw keyboard input with
crossterm. - Read raw stdout bytes from the PTY and manage buffer state internally (
PipeStatevsCmdlineState). - Hack around command boundaries by injecting environment variables (
PROMPT_COMMAND='echo __AGENT_DONE__:$PWD').
It didn't take long to realize this was the wrong approach:
- Handling raw ANSI escape codes, terminal resizing, cursor coordinates, and key events is a massive, brittle maintenance burden.
- Worse, wrapping a terminal breaks the developer's environment—custom shell prompts, aliases, keybindings, and shell plugins broke or suffered from input latency.
Reinventing terminal emulation just to offer command completions was not worth it.
The pivot: Deleting the emulator and hooking into Zsh
In late February, I deleted roughly 1,500 lines of emulator and PTY code in one commit (5c240b0).
Instead of wrapping the shell, I decoupled the tool into two clean pieces:
- A standalone Rust CLI: It takes shell context, talks to LLM providers, and outputs recommendations over a lightweight stdout protocol.
- A Zsh integration script (
smart-terminal.zsh): It hooks directly into the Zsh Line Editor (ZLE). PressingCtrl+Gcalls the binary, renders the suggestion as inline ghost text, and pressingCtrl+Fdrops only the command into the editable buffer.
This meant my terminal, prompt, and shell configuration remained 100% native, while suggestions stayed fast and unobtrusive.
Learning agentic concepts through daily use
Once the interface was out of the way, I could focus on the actual intelligence. Because I was using the tool daily, every edge case or annoyance turned into an architectural improvement:
-
next-cmd& Reversibility: Suggestions based on recent history, current folder, and partial inputs were useful, but running unknown commands blindly is stressful. I added a fast reversibility heuristic that flags predictions from safe/read-only (ls) to irreversible (rm -rf), giving a clear visual safety cue before accepting. -
investigate: I wanted to ask questions about unfamiliar repos without leaving the terminal. Rather than just feeding context to an LLM, I built a ReAct agent loop. A planner inspects the directory structure and emits a plan, and an executor carries it out using safe shell tools (read_file,read_dir,bash,docker,git_diff), keeping a durable scratchpad as it works. -
memory: Project-scoped persistence that remembers past commands and context so suggestions sharpen over time without mixing up different workspaces. - Provider layer: Clean traits abstracting LLM calls across Groq (for near-instant command predictions), Google Gemini, and OpenRouter.
The codebase is split into modular layers (src/cli, src/core, src/agent, src/persistence, src/providers, src/tools) and backed by integration tests.
Why I'm opening it up
I'm an undergraduate student at the University of Athens, and I've reached a point where I need to move on to other priorities and stop active work on this repo.
What started as a small portfolio project turned into a dependable tool I use daily and a deep dive into agentic systems. Rather than letting it sit idle, I'd like to put it out there for anyone interested in hacking on it.
The architecture is solid and there are a few obvious areas where contributors could take it further:
- Other shell integrations: The hook currently only targets Zsh. Adding Bash, Fish, or Nushell hooks would be a great addition.
- Local LLM support: Adding an offline provider like Ollama or
llama.cppso users don't need API keys. - New investigation tools: Adding tools like ripgrep or test runner output parsers.
- Maintenance: If someone wants to triage issues or help maintain the project, I'm happy to grant access.
If you're interested in checking out the code or contributing:
- Repository: github.com/sdi2200246/smart-terminal
- Contributing guidelines: CONTRIBUTING.md
PRs, questions, and feedback are all welcome.