DEV Community

Cznorth
Cznorth

Posted on

WinkTerm: AI That Shares Your Terminal Session, Not Just Suggests Commands

#ai #opensource #devops #productivity

I have a problem with "AI in the terminal" tools.

They're almost all the same: a chat sidebar. You ask a question, the AI replies with "try this command", and you copy-paste. The AI never actually sees what your shell sees — it has no idea whether you're root, whether that command succeeded, what $PWD is, or what the error two lines up was. It's a knowledgeable friend you have to dictate everything to over the phone.

I wanted a friend who could just reach across and type.

So I built WinkTerm — an MIT-licensed AI terminal where the AI and I share the same PTY.

How it actually feels

You're at your shell prompt. You type # what's wrong with this VPN config. The AI answers in the same terminal, then pre-fills its suggested fix into your input line. You press Enter to run it. Backspace to edit. Ctrl+C to throw it out.

$ ipconfig
Command 'ipconfig' not found, did you mean: ...
$ # what's wrong
[WinkTerm] `ipconfig` is a Windows command — on Linux use `ip addr`.
$ ip addr█   ← AI wrote this. Press Enter to run.
Enter fullscreen mode Exit fullscreen mode

The AI sees what you see because it is in the same session. When it runs a command, the output is real shell output, with real exit codes, in your real cwd. When you run a command, the AI remembers it as context for the next turn.

Why this matters

Sidebar chatbots are great until reality hits — env vars you set last command, a multi-step debugging session, a partially-applied migration. The chatbot has no idea any of that happened. The shared-PTY model means the AI inherits the same context drift your hands do.

It also keeps you in control. The AI never runs a command without you pressing Enter (by default). Pre-fill, not auto-execute. You stay the operator.

What's in the box

  • Shared PTY chat — # message triggers AI inline
  • Sidebar AI panel — when you do want a longer conversation, with multi-tab chats and AI-generated titles
  • Multi-model — Anthropic / OpenAI / Ollama / any OpenAI-compatible endpoint
  • SSH — built-in remote connections with file transfer
  • Persistent history — chat survives reconnects and backend restarts
  • Streaming resume — refresh mid-response without losing tokens
  • HTTP Agent API — Claude Code / Cursor can drive terminals + SSH remotely
  • Deploy any way you want — Docker, Win/macOS desktop app, or an Android thin client

Stack

  • Backend: Python, FastAPI, LangGraph for the agent state machine, native PTY (pty/winpty)
  • Frontend: Next.js 14 (App Router) + xterm.js
  • Protocol: WebSocket for the terminal stream; # lines are intercepted before they hit the shell and routed to the agent

Data flow 

User keyboard input
    │
    ▼
Frontend Terminal (xterm.js)
    │  WebSocket
    ▼
ws_handler.py
    │
    ├── normal input ──► pty_manager.write() ──► shell process
    │
    └── # lines ──► intercept ──► Agent (LangGraph) ──► pty output
Enter fullscreen mode Exit fullscreen mode

Agent output is written back as PTY output — it shows up in the same scrollback as everything else. The "AI" is just another writer to the same fd.

Status

MIT, ~3.5 months old, runs on my own infra daily. I'd love feedback — especially from people who've also been frustrated by sidebar-style AI terminals.

GitHub: https://github.com/Cznorth/winkterm

Top comments (0)