Open Source Coding Agents: Aider, OpenHands, and Friends
What the open alternatives do well, and where the polish gap actually matters.
Last time we saw how coding tools find the right code in big repositories. This time we open up the open-source agents, which let you own and inspect that machinery yourself. The short version: the things they do well are things you cannot buy, such as full transparency and control, and the things that still sting are exactly what polished products smooth over.
Aider builds a ranked map of your repository's most-referenced symbols that fits in about 1,000 tokens by default, and grows it when the model needs more, as its repository map documentation explains. It does this without a vector database, without embeddings, and without sending the whole codebase to the LLM (large language model). A graph ranking algorithm picks the few symbols the rest of the code leans on most, and the model works from that map.
How does Aider build its repo map, and why does graph ranking work where brute force fails?
Aider's core trick is its repository map. When you ask for a change, it sends the model a concise list of the most important classes, functions and type signatures in your codebase, each tagged with the file that defines it. This map is what the model sees alongside your request, not a sea of raw code.
The map is more than a file listing. Aider builds a graph in which each source file is a node and an edge connects files that depend on each other. Then it ranks the graph with an algorithm in the family of PageRank, the method Google first used to rank web pages by how many important pages link to them. Here the question becomes: which files and symbols are referenced most by the rest of the code, especially by the files you are working on? Those rank highest and go into the map.
The token budget is set by --map-tokens and defaults to about 1,000 tokens. Aider keeps the top-ranked symbols that fit and adjusts the size as the chat goes on; the map can grow when you have not added any files yet and the model needs a wider view. When the model needs full file contents, you add those files to the chat. It is the same reasoning and action loop we met in Part 1, except the environment is a Git working tree and the tool is a text-based CLI (command-line interface).
The design sidesteps the embedding pipelines and vector stores that other tools have invested in, and it works because code symbols already carry a lot of meaning. A senior engineer reading the map can guess how to use a module; so can a language model. Aider does not have to guess which files matter. The graph tells it.
That is the strength, and also where the polish gap shows. The map reflects the code's structure and the current chat, not its history: it knows nothing about which parts changed recently or which ones a teammate is working on, and it cannot use runtime traces or test coverage the way a richer system might. In a monorepo of loosely connected services, one big graph can blur boundaries and pull in symbols from the wrong service. Aider gives you full transparency and no black boxes, but you will feel the absence of the "works out of the box" smoothing that Cursor or Copilot spend years on. Check a project's activity before you adopt it, too: as of October 2026, Aider's main repository had not been updated since May 2026.
How does OpenHands use event sourcing to keep agent state safe and replayable?
If Aider is a smart CLI, OpenHands is a factory for building and running agents. Its Software Agent SDK (software development kit) provides agents, tools, workspaces and an Agent Server with a REST API, and the OpenHands app, now called Agent Canvas, gives you a graphical interface that can run OpenHands' own agent or third-party agents such as Claude Code, Codex and OpenCode, locally, on remote machines or in OpenHands Cloud.
The SDK leans on one design decision that changes everything. As its event system documentation puts it, events form an append-only log that serves as the agent's memory: every user message, action, observation and state update is an immutable, typed event added to the log, and the conversation's state comes from that history.
This matters because agents crash. An LLM call fails, a workspace container is evicted, a tool call times out. In an ad hoc system, recovering means hoping the in-memory structures are still valid. With an event log, the conversation persists its events and can pick up from what was recorded. It is the same pattern behind financial ledgers: you get an audit trail for free, and debugging becomes reading a timeline.
Safety sits in front of execution. The SDK's security guide describes two mechanisms that work together: a security analyzer that rates the risk of each action before it runs, and a confirmation policy that decides when you must approve it. The workspace that runs the code can be your local machine for fast iteration or a Docker container for untrusted work. Because the event log records every decision, you can see exactly which action ran and whose approval let it through.
The polish gap here is a real setup tax. Building a workspace that mirrors your actual development environment, with the right compilers, package managers and credentials, takes work, and you design your own security policy rather than inheriting a vendor's. The closed tools hide this complexity; OpenHands gives you the parts and expects you to assemble them.
What is an Agent-Computer Interface, and why did SWE-agent invent one instead of using a shell?
SWE-agent, from researchers at Princeton, introduced the idea of an Agent-Computer Interface (ACI). The argument is simple: interfaces built for humans, like a raw Linux shell with full rm -rf power, are a poor match for an LLM. A model does not need tab completion, history scrolling or colour codes. It needs a small set of operations that are easy to predict and hard to misuse. So SWE-agent defines its own commands for moving around the file tree, searching for code, opening files with line numbers, editing specific ranges and running tests, and each returns a concise, structured observation instead of raw output.
- Raw bash commands
- Unbounded output
- Easy to run destructive commands
- Small set of structured commands
- Concise, bounded observations
- Edits limited to specific line ranges
When SWE-agent works on a GitHub issue, it does not drop into an open-ended shell session. It uses its ACI commands to find, open, edit and submit, and the harness runs them in a Docker sandbox and returns a clean summary. The authors showed that this interface design improved results on the SWE-bench benchmark (Yang et al. 2024, SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering): with a constrained action space, the model makes fewer catastrophic mistakes and recovers from errors more easily.
Cline takes a different path to a similar end. It splits work into two modes, as its Plan and Act guide describes: in Plan mode it can read your code, search and discuss a strategy but cannot change files or run commands; in Act mode it carries out the plan, and every file edit and terminal command needs your approval unless you turn on auto-approve. Cline also keeps a shadow Git repository, separate from your project's history, and commits your files to it after each tool use, so checkpoints let you roll back an agent's changes without touching your real branch.
Both are safety wins over a general-purpose terminal agent, and both have integration costs. SWE-agent was built for research benchmarks, so its setup assumes a clean Docker environment without corporate network quirks or local secrets to handle carefully. Cline began as a VS Code extension and now also ships a CLI, a JetBrains plugin and an SDK, but its interactive approval flow fits a person at a keyboard better than an unattended pipeline. These are trade-offs a capable team can work around, and exactly the friction a packaged product removes before you ever see the source.
What about the open-source CLIs from the big AI labs?
Some of the most widely used open-source coding agents come from the companies that make the models. They are terminal agents, like Claude Code, but their source code is public:
- OpenAI Codex CLI (Apache 2.0) runs on your computer, and you sign in with a ChatGPT plan or use an API key. It is built around OpenAI's models, though its advanced configuration lets you add other model providers, and it has a non-interactive mode for scripts.
- Gemini CLI (Apache 2.0) is Google's terminal agent for Gemini models. Google announced in May 2026 that from June 18, 2026, its free and consumer subscription users move to a new Antigravity CLI, while Gemini CLI stays available with paid Gemini API keys and enterprise plans.
- OpenCode (MIT) is independent of any model maker: it works with more than 75 model providers and can run local models, as its providers documentation says.
The lab CLIs are a natural fit when you already pay for that lab's models; OpenCode and Aider fit when you want to switch models freely or run them locally. All of them share the same basic loop: search, read, edit, run, and check the result.
Quick Reference
| Property | Aider | OpenHands | SWE-agent | Cline |
|---|---|---|---|---|
| Repo context strategy | Graph-ranked repo map, files you add | Workspace plus agent search | ACI commands for search and file view | Editor workspace, agent search and file reads |
| State management | Chat history; every change committed to Git | Append-only event log | Per task | Per task, with shadow Git checkpoints |
| Safety model | You review each commit, /undo; optional lint and test runs | Security analyzer plus confirmation policy; Docker workspaces | Constrained commands in a Docker sandbox | Plan mode is read-only; approval for each edit and command in Act mode |
| Action space | File edits in text edit formats | CodeAct (Python or bash) and tools | Custom ACI commands | File edits, terminal, browser |
| Integration | Terminal CLI | SDK, Agent Server, Agent Canvas, OpenHands Cloud | Docker sandbox, research harness | VS Code, JetBrains, CLI, SDK |
| Source | aider.chat | OpenHands GitHub | SWE-agent GitHub | Cline GitHub |
OpenHands' CodeAct approach lets the agent act by writing and running code rather than only calling fixed tools (Wang et al. 2024, Executable Code Actions Elicit Better LLM Agents).
Frequently Asked Questions
Q: Can I point Aider at a monorepo that isn't a single Git root?
Aider works within one Git repository. For a monorepo, start Aider in the subdirectory you care about with --subtree-only, which makes it consider only files in that part of the tree, and list paths to skip in an .aiderignore file at the repository root, as its options reference describes. Then add only the files you need to the chat.
Q: How does OpenHands prevent the agent from running dangerous commands in my local terminal? Run it in a Docker workspace, so the filesystem and network the agent sees are isolated from your machine. Then set the security analyzer and confirmation policy so that risky actions need your approval. Review those settings for your own setup; no automated policy can anticipate every possible shell command.
Q: Is SWE-agent suitable for daily development, or is it just a research tool? It was designed for research and benchmarks, around short-lived Docker environments. You can point it at a real repository, but most teams treat it as a reference design for agent interfaces rather than a daily driver.
Q: How does Cline's shadow Git repository differ from Aider's auto-commits?
Aider commits directly to your working branch, so your real Git history contains the agent's changes, and you revert them like any other commit or with /undo. Cline keeps a separate shadow repository that records every step but never touches your project's history, so you can roll back an agent session and still decide yourself what to commit. One is a safety net; the other is a permanent audit trail.
Q: Which tool should I pick if my team wants to embed agents into CI/CD (continuous integration and continuous delivery)? OpenHands is built for it: its Agent Server exposes a REST API you can call from CI jobs, and its event log records every action for review. Aider is easy to script for single tasks but was not designed as a multi-user server. The lab CLIs also run without a person at the keyboard, Codex CLI through its non-interactive mode, which is worth comparing for simple pipeline jobs.
Test yourself
Your team is maintaining a large Python monolith with 200,000 lines of code spread across 80 packages. You want to use an open-source agent to perform a refactoring that touches the data access layer, which is imported by nearly every package. The agent must run inside your existing CI pipeline, leave a clean audit trail, and never have permission to push to the main branch directly. Which tool would you use, and what would you configure to meet these requirements?
Answer: OpenHands fits best. Run its Agent Server inside the pipeline with a Docker workspace that mirrors the monolith's build environment: the same Python version and dependencies. Its append-only event log is the audit trail; ship the events to your pipeline's log store. Set the confirmation policy and security analyzer to stop risky actions, and do not rely on them alone for the push rule. Give the container a token that can push only to a feature branch, and protect the main branch on the server so a direct push fails whatever the agent tries. Have the agent commit to that branch and open a pull request for human review. Aider is a weaker fit because it was built for a developer at a terminal, and Cline's approval flow expects someone at the keyboard.
Next: Designing Your Personal AI Coding Workflow. It brings the series together into a weekly workflow: which mode to use for which task, how to plan, and how to keep changes small and reviewable.
If you want this kind of breakdown every week, how real systems actually work under the hood, subscribe to Internals Decoded at internalsdecoded.com.
Sources
- Aider: Repository map
- Aider: Options reference
- Aider: Linting and testing
- OpenHands Software Agent SDK
- OpenHands SDK: Events
- OpenHands SDK: Security and action confirmation
- SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering
- Executable Code Actions Elicit Better LLM Agents
- Cline: Plan and Act
- Cline: Checkpoints
- OpenAI Codex CLI
- Codex: Advanced configuration
- Codex: Non-interactive mode
- Gemini CLI
- Transitioning Gemini CLI to Antigravity CLI
- OpenCode
- OpenCode: Providers
- github.com · Cline
- aider.chat
- OpenHands GitHub
- SWE-agent GitHub
