Joel's Blog

Anatomy of an Open Source AI Coding Agent

Motivation: What goes into a chat-with-ai site? What would it take to build and configure one

What’s out there?

  1. OpenCode. A terminal based AI coding agent
  2. app.build. Databricks / Neon’s Agent that generates working applications
  3. Adorable Freestyle.sh’s take on a Lovable clone.
  4. Dyad.sh. Desktop based Open Source alternative to Lovable.
  5. Bolt.diy. Open Source version of Bolt.

If you know of other Open Source Application builders you are welcome to let me know in the comments.

This article by Thorsten Ball is a good starting point for an overview of coding agents. If you have not read it, please do so as I will skim over concepts like tool calls which are covered in the article

Tool Calls

What’s a Tool? Here’s what Thorsten says in the article:

The basic idea is this: you send a prompt to the model that says it should reply in a certain way if it wants to use “a tool”. Then you, as the receiver of that message, “use the tool” by executing it and replying with the result. That’s it. Everything else we’ll see is just abstraction on top of it.

Main tool calls needed are edit_file, write_file, and read_file. In practice, the agents use more tools than that - here’s a list of OpenCode tools at time of writing. Table generated by Claude Code.

Tool Name Category Purpose Key Features
bash System Execute shell commands • 10min timeout• Working directory aware• Stdout/stderr capture• Exit code tracking
read File I/O Read file contents • 250KB max size• Line-based reading (offset/limit)• Smart file suggestions on 404• Truncates long lines (2000 chars)
write File I/O Create/overwrite files • Permission system integration• File existence checking• Event bus notifications• Absolute path enforcement
edit File I/O String replacement in files • Exact string matching• Replace all option• Diff generation• Permission gating• LSP integration
multiedit File I/O Multiple edits in sequence • Batch edit operations• Sequential execution• Single permission request• Atomic operation
patch File I/O Apply unified diff patches • Full patch parsing• Multi-file support• Add/update/delete operations• Context-aware application
list Discovery Directory listing • Smart ignore patterns• 100 item limit• Absolute path requirement• Common dev folder filtering
glob Discovery Pattern-based file matching • Ripgrep-powered• Modification time sorting• 100 file limit• Recursive search
grep Search Text search in files • Ripgrep backend• Regex support• File pattern filtering• Line number output
lsp_diagnostics Code Intelligence Get TypeScript/LSP errors • Language server integration• File-specific diagnostics• Pretty error formatting• Real-time analysis
lsp_hover Code Intelligence Get symbol information • LSP hover information• Position-based queries• Type definitions• Documentation extraction
webfetch External Fetch web content • HTML to markdown conversion• 5MB size limit• 2min timeout• Format options (text/markdown/html)
todowrite Task Management Manage AI task lists • Session-scoped todos• Status tracking (pending/in_progress/completed)• Priority levels• JSON persistence
todoread Task Management Read current todos • Session-specific retrieval• Status filtering• Progress tracking• Metadata access
task AI Orchestration Spawn sub-agent sessions • Creates new AI session• Delegates complex tasks• Real-time progress monitoring• Result summarization

The lsp specific tools are unique

Tool Categories & Capabilities

Here’s a breakdown of the tool functions

File Operations (Core)

  • read/write/edit: Basic file manipulation with permission system
  • multiedit: Efficient batch editing for complex refactoring
  • patch: Git-style unified diff application for precise changes

Discovery & Search

  • list: Directory exploration with smart filtering
  • glob: Pattern-based file discovery with performance limits
  • grep: Fast text search using Ripgrep for codebase analysis

Code Intelligence

  • lsp_diagnostics: Real-time error detection and type checking
  • lsp_hover: Symbol information and documentation lookup
  • Integration with LSP servers for TypeScript, Python, Go, etc.

System Integration

  • bash: Full shell command execution with proper isolation
  • webfetch: External content retrieval for documentation/research

AI Orchestration

  • todowrite/todoread: Task planning and progress tracking
  • task: Sub-agent delegation for complex multi-step operations

Core Agent Loop

App.build’s loop app_dot_build_architecture.png

Choices around Memory

Memory is used to store conversation history and ensure appropriate generations

  1. Mastra for memory
  2. Redis PubSub for Streaming
  3. app.build has an LLM Cache
  4. OpenCode seems to use an .md file

Investingating the System Prompt

  1. Bolt.diy System prompt https://github.com/stackblitz-labs/bolt.diy/blob/main/app/lib/common/prompts/new-prompt.ts
  2. Adorable System Prompt https://github.com/freestyle-sh/Adorable/blob/main/src/lib/system.ts

Choices around Auth

Mostly standard OAuth login. Adorable uses Stack Auth while app.build uses Neon Auth. Bolt.diy and dyad seem to use Supabase Auth?

Permissioning

  1. Mostly done via a table in Postgres where needed. Or not needed from the outset

Template Repositories

  1. Mobile
  2. Next.js
  3. Vanilla React
  4. trpc

Dealing with Containers

  1. Dagger a. Describe how it is used
  2. Freestyle.sh
  3. Webcontainers

Notable features

  1. Git Integration
  2. Deployment and generation

References

  1. Gemini Quickstart. Google’s take on an open source deep research
  2. app.build blog. Documents aspects of app.build architecture
  3. Freestyle.sh docs. An overview