I wanted to learn how coding agents work, so I built one and want to share what I learned
Hey everyone!
I'd like to share a project I've been working on, it's called Orin and it's a coding agent.
I use coding agents constantly, and at some point I realized I had basically no idea what was happening between me hitting enter and code showing up.
Also I was tired of building apps I wasn't able to really debug because I didn't know how they were being built in the first place so I got busy studying: read a bunch of articles, still felt like a black box, so I just tried to build one.
Couple things worth saying before anyone digs in:
It's mostly AI-written code, no point in hiding that, but I don't think "written by AI" and "sloppy" have to go together.
I try to run all my projects in the most professional way I know of, following actual SDLC practices: spec first, then an issue, then the implementation, then a real PR review before anything merges, not vibe-coding where you just accept every diff.
Whether that shows in the actual code is for other people to judge, not me.
Also this isn't some original idea I came up with: I cloned and read through pi.dev, nanocoder, and opencode as primary references (and skimmed Cline/Kilo Code for patterns), and basically tried to take what made sense to me from each and put it into one implementation.
My whole idea was try and build something that took the best from each to make a coding agent that would perform well. I plan to benchmark it on SWE-bench Verified sooner or later, but I don't think it's ready just yet: there are rough edges and bugs, but its usable.
Some of the actual implementation stuff, for anyone who cares about those rather than the pitch:
- The loop is just: stream a response from the provider, push it to message history, if there are tool calls run them, push the results back, repeat until there's nothing left to call.
- The loop is completely headless — it doesn't touch the terminal, it just emits events. The TUI (SolidJS on top of OpenTUI, just like opencode) is a separate subscriber to those events. You could swap in a totally different frontend without touching the loop at all.
- Another thing I got from OpenCode are edits: they go through a fuzzy replacer chain, not a single exact string match — if the model's oldText is off by whitespace or indentation, it falls through a chain of matchers before giving up. I had never thought about this and can confirm it's the kind of thing you don't appreciate until you actually try to implement it.
- There's a model routing mechanism that switches different models based on what the agent has to do:
- explore runs on a cheap/fast model by default,
- implement on a code-tuned model,
- review on the main model.
- Another thing I borrowed from the web is a delegate_read tool that lets the main agent hand off read-heavy grunt work (scanning a big file, summarizing logs) to a cheap model so that content never bloats the main context.
- It's basically a one off LLM call that only returns a distilled summary, seems dumb but works surprisingly well with capable models like Claude who know exactly what to look for and delegate super well to other agents.
- Tool selection isn't a static allow-list. Every turn runs a BM25 retrieval pass over the full tool catalog (including MCP tools) via a super cool library called Ratel, so the model only ever sees the tools relevant to what it's doing in that specific turn instead of the whole catalog every time. There's even an A/B flag to compare tool_pool=ratel vs tool_pool=default in your own telemetry to see if it even makes a difference (similar to how rtk gain works).
- Every file write gets snapshotted into a shadow git history before it happens, including stuff done through raw bash — allowing the agent to have a proper /undo /redo command.
- When I implemented subagents I wanted to explore different isolation mechanisms and ended up with 3 different ones you can configure yourself:
- shared (edits land on the main working tree, safe because they run serially),
- worktree (isolated branch)
- sandbox (a real E2B cloud VM, edits get thrown away on dispose — for code you don't trust at all).
- The lead model can escalate isolation for a given task but never go below the configured floor.
- I implemented hooks borrowing from nanocoder and opencode. This allows the agent to be expanded by third party code and I bundled some sensible defaults:
- there's a before_tool hook that rewrites bash commands through rtk so that command output gets compressed before it ever reaches the model.
- In my daily work I build AI agents and vibe coded internal tools for my company and after a while I saw how much telemetry is crucial for debugging and actually understanding agent behaviour, so I decided that my agent would ship native OTLP tracing by default.
- This means that by adding just one environment variable you can see full traces in your telemetry platform (Langfuse, Tempo, Jaeger, whatever you like) out of the box.
- Orin is also provider-agnostic (currently supports OpenRouter, OpenAI, Anthropic, OpenCode Go/Zen and Regolo if you want an EU-hosted option) — switching provider or model happens at runtime through a provider registry, no restart needed.
None of this is groundbreaking, it's just what I landed on after reading other people's code and deciding what to keep.
Try it:
git clone https://github.com/thetombrider/coding_agent.git
cd coding_agent
./install.sh
orin
There's also a deepwiki writeup if you want the architecture without reading source: https://deepwiki.com/thetombrider/coding_agent
I would really appreciate feedback in any shape or form. I'm learning and sharing my journey, hope it helps someone.
