The Terminal Coding Agent I Use to Run My Own Servers
Most AI coding tools live in your editor, run in someone else’s cloud, and hide how they work behind a panel. That’s fine right up until you’re the person who runs the boxes and wants to actually understand the tool doing the work. That itch is why I built lean-coder, and it’s what I now use to get real work done on my own servers. Here’s what it is and the thinking behind why it works this way.
What it actually is
lean-coder is a single-file agent you run from the command line. No IDE plugin, no web UI. You open a terminal, talk to it in a prompt, and it plans, edits files, and runs commands while you watch. I kept the core at zero third-party dependencies (Python standard library only) on purpose: it should be small enough that you can read the whole thing and know exactly what it does before you trust it on your boxes.
The part that matters day-to-day is that it works on my machines, not in a sandbox. It can run its tools on a remote box over SSH: the agent’s brain runs locally, but the file edits and commands execute on the server you point it at. The experience is identical whether I’m on my laptop or on a VPS in a data centre.
The moment it clicked
The example that convinced me the design was right was a headless server that had started misbehaving, the kind of intermittent fault where everything looks fine when you log in to check, and you can’t reproduce it on demand. Normally that means an evening of tailing logs and second-guessing yourself.
Instead I pointed lean-coder at the box, let it SSH in, and worked through it conversationally: read the service logs, spotted the failing component, applied the fix, restarted, and confirmed it came back clean, all in one session. It did the actual work on the actual machine, not “here’s a snippet, go paste it somewhere,” but the real thing, in front of me, with a confirmation gate before anything ran.
That’s the difference. It’s not a thing that writes code in a bubble. It’s a thing that does the job on the system that matters.
Bring your own model
lean-coder isn’t tied to one AI vendor. It talks to several backends through a clean provider layer:
- Local models via Ollama: run everything on your own hardware, nothing leaves the box.
- Anthropic, OpenAI, Google Gemini, Groq: bring your own API key when you want a frontier model.
Switching is a command, not a reinstall. I run a cheap local model for routine work and reach for a stronger hosted one when a task actually warrants it, without changing tools.
It’s built for long sessions
Real work doesn’t fit in a tidy five-message chat, so I built it to hold up over a long, messy session. It quietly trims old tool output so the context window doesn’t choke, it can summarise a long session into a compact briefing and reset cleanly so you keep going instead of starting over, and a pinned plan (the goal and a checklist) survives all of that so it never loses the thread.
There’s also an /activity log that shows every automatic thing it did, each with a plain-English reason. The first time a session compacted itself mid-task I thought something had broken; the log made it obvious it had just handled it.
Handover is the feature I didn’t know I needed
The feature I’m proudest of, and the one that changed how I work, is auto-handover. I run Opus 4.8 with a million tokens of context available, but a million tokens is not the flex it sounds like. In a typical GUI you can push past 500,000 tokens before the interface even renders the little indicator telling you you’re at fifty percent, and by then quality has already started to sag. The context you keep feeding a model is not free; the fuller it gets, the more the model drifts. That problem is exactly what handover exists to solve.
So lean-coder hands over early and deliberately. I set the handover to trigger around 250,000 tokens and I almost never go much beyond it. The reason I’m never nervous about handing over is that it does the whole ritual for me: it updates the docs on the machine, pushes to git, updates its own to-do list, and writes itself a handover briefing. It even writes the message it wants to receive when it comes back, then feeds that message to the fresh session as its opening prompt. The new session picks up exactly where the old one meant to, without me reconstructing anything.
It’s also polite about timing. Before it hits the hard limit, it gets prompted at a soft limit and tries to find a clean break point in the workflow rather than tearing out mid-task, and it checks in with me at that point. The handover tool is handed to the model to use at its own discretion once it’s past the soft limit, so if I’m happy for it to go I can just tell it to hand over. And the whole time, the context usage is displayed as you work, so you’re never guessing how full the tank is.
Safety you can reason about
Because it acts on real machines, the safety model matters, and it’s refreshingly explicit rather than one on/off switch:
- A leash sets a hard ceiling: chat-only, read-only, or read-write-execute.
- Confirmation prompts gate actions, from “ask every time” to “approve for this session.”
- Tools that must stay local are marked as such and are never pushed to a remote box.
- Hand-off to you for anything it shouldn’t see: it can surface a command for you to run yourself, so a password, a
sudoprompt, or a script that rotates an auth token is typed into your own terminal and never passes through the model.
It isn’t trying to wrap you in cotton wool. It just makes the boundaries predictable, which is exactly what you want from something that can run commands on your infrastructure.
That hand-off is worth dwelling on, because it solves a real tension. Plenty of jobs need a secret the agent has no business holding: entering your login password, clearing a sudo gate, pasting a one-time code, or running a script that writes a fresh auth token to disk. Rather than asking you to hand over the secret, it composes the exact command and passes it to you. You see precisely what it wants to run, edit it if you disagree, then run it in your own terminal and enter whatever it needs. The result comes back; the secret never does. You get the convenience of the agent doing the legwork without ever trusting it with credentials.
Getting started
It runs on Linux, macOS, WSL, and even Termux on Android. You need Python 3.11+. It installs as a single script symlinked onto your PATH.
curl -fsSL https://raw.githubusercontent.com/codemonkeying/lean-coder/main/install.sh | bashIf you’d rather see exactly what you’re running, clone it and install from the repo:
git clone https://github.com/codemonkeying/lean-coder
cd lean-coder
./install.shThen run lean_coder, start typing, and use /help to see everything it can do. The repo is here: https://github.com/codemonkeying/lean-coder
Is it for you?
I’ll be honest about who this suits, because I built it deliberately narrow. If you live in a terminal, run your own servers, care about keeping your code and your models under your own control, and like tools you can read and extend, it’s built for you. If you want a polished, hand-holding assistant that hides the machinery, this isn’t that, and I never set out to make that.
For me, that narrowness is the whole point. It does real work where I need it, on the machines I actually care about, and it tells me what it’s doing while it does it. That’s exactly what I wanted from one of these things, so I built it.
The short version
A coding agent that lives in your terminal and runs on your machines. Zero core dependencies. Any model, whether local via Ollama, or Anthropic / OpenAI / Gemini / Groq with your own key. It edits files and runs commands right where you work, including on remote servers over SSH, with a safety leash and confirmation gates you control. The killer feature for real work is auto-handover: at a soft limit it finds a clean break point, writes its own briefing, updates the docs, pushes to git, and hands the whole session to a fresh one that picks up exactly where it left off, so quality never rots as the context fills. Your context usage is on screen the whole time. One file, no black box, no lock-in.
- 🖥️ Terminal-native: no IDE plugin, no web UI, no cloud middleman.
- 🔓 No lock-in: bring your own model and keys; run everything locally if you want.
- 🌐 Real work on real servers: tools execute over SSH on the machine that matters.
- 📉 Made for long sessions: smart context management that tells you what it’s doing.
- 🔧 Hackable: tools and model backends are plugins; add your own in a small file.
- 📖 Readable: it’s one file you can actually understand and trust.
Leave a Reply