Learnimal

An agentic terminal you can learn with - an Alacritty fork with AI-powered explanations and privacy-focused assistance (Ctrl+Shift+E)

Comment

Inspiration

Learning Linux is hard. When you're stuck on a cryptic error or can't remember what a flag does, the instinct is to alt-tab to a browser, wade through Stack Overflow, and lose your flow entirely. We wanted to remove that friction: what if the terminal itself could teach you, right where you're already working? Enter Learnimal: an AI tutor baked directly into the terminal emulator, so help is always one keystroke away.

What it does

Learnimal adds an AI-powered learning overlay to your terminal. Press Ctrl+Shift+E at any moment and a panel appears inside your terminal window with an explanation of what's on your screen. It can break down command syntax, diagnose errors and suggest fixes, and surface relevant context from your own command history. Everything runs locally, so there's no account, no API key, and no data leaving your machine.

How we built it

We forked Alacritty, a GPU-accelerated terminal emulator written in Rust, and extended it at three layers:

  • Grid extractor: when you press the hotkey, Rust code reads the live terminal grid, truncates it intelligently (first 40 + last 40 lines, capped at 8,000 chars), and POSTs it as JSON to a local server.
  • AI backend: a Python FastAPI server runs a ReAct agent built with AdalFlow, backed by Llama 3 8B running locally via Ollama. The agent has three tools: syntax explanation, error remediation, and historical query lookup. Interaction history is stored in SQLite with FTS5 for fast recall.
  • Overlay renderer: the response streams back as server-sent events, and Rust renders an incremental panel at 60% terminal width, updating in real time as tokens arrive.

Challenges we ran into

  • Forking Alacritty was non-trivial: the codebase is large and the rendering pipeline is not built to be extended. Getting the overlay to draw correctly without corrupting the underlying terminal grid took significant trial and error.
  • Streaming into a Rust renderer required careful coordination between the SSE response chunks coming from Python and the 16ms repaint cycle in the overlay.
  • Reliable last-command detection was much more difficult than expected. The terminal grid is just characters: there's no semantic boundary between prompt, command, and output, so we had to be creative about how we identified what the user had just run.
  • Keeping the agent responses fast enough to feel interactive while running fully on-device was a constant balancing act.

Accomplishments that we're proud of

  • A genuinely end-to-end working prototype: press a key, get a streamed AI explanation, entirely within the terminal, all built in 8 hours.
  • The overlay feels native. It's not a popup or a separate window; it lives inside the emulator itself. Fully local and private, no cloud dependency, no usage tracking. The model runs on your machine.
  • A clean two-engineer architecture where the Rust and Python halves could be developed in parallel with a clear IPC contract from hour one.

What we learned

  • Rust's ownership model is both the best and worst thing about modifying a complex codebase under time pressure.
  • ReAct agents are surprisingly effective for this kind of multi-tool reasoning: the structured think/act loop made the agent's behavior much more predictable than a raw prompt would have been.
  • Designing the IPC contract before writing a single line of feature code was a good decision because it let both engineers work in parallel with confidence.

What's next for Learnimal

  • Packaging Learnimal so it's easy to install on Ubuntu, Fedora, and Arch, not just from source.
  • Going beyond the visible grid to include shell history, environment variables, and the current working directory.
  • Using the SQLite history to identify patterns in what a user struggles with and proactively surfacing relevant tips.
  • Letting users swap in different local models or optionally connect a cloud provider for higher-quality responses.
  • A VS Code / Neovim plugin to bring the same overlay experience to users who live in editor-integrated terminals.

Built With

Share this project:

Updates