Exploring the architecture of coding agents by rebuilding a Claude Code-style CLI from scratch in Swift.

A complete 9-part learning series is available on ivanmagda.dev.
Claude Code feels unusually effective compared to other coding agents, and I suspect most of it comes from architectural restraint rather than architectural complexity. I studied the tool surface, traced the interaction loop, and tried to isolate which design choices actually matter.
My working theory: coding agents benefit more from a small set of excellent tools and tight loop design than from large orchestration layers.
Claude Code doesn't have many tools. The tools it does have are simple: a search tool, a file editing tool. But those tools are really good. And the system leans on the model far more than most agent implementations β less scaffolding, more trust in the LLM to do the heavy lifting.
This project tests that idea by rebuilding the core mechanics from scratch in Swift, one stage at a time, to see how little architecture you actually need.
This project tests a few specific ideas about coding agents:
Each stage is designed to isolate one mechanism and see what it enables.
The whole thing boils down to one loop:
func run(query: String) async throws -> String {
messages.append(.user(query))
while true {
let request = APIRequest(
model: model, system: systemPrompt, messages: messages, tools: Self.toolDefinitions
)
let response = try await apiClient.createMessage(request)
messages.append(Message(role: .assistant, content: response.content))
guard response.stopReason == .toolUse else {
return response.content.textContent
}
var results: [ContentBlock] = []
for block in response.content {
if case .toolUse(let id, let name, let input) = block {
let output = await executeTool(name: name, input: input)
results.append(.toolResult(toolUseId: id, content: output, isError: false))
}
}
messages.append(Message(role: .user, content: results))
}
}
The loop is the invariant. Tools are the variable. Every stage adds entries to the tool handler dictionary and injection points before the API call, but the loop body itself never changes.
Progress is tracked via git tags. The roadmap is split into two phases β core mechanics first, then product-level features.
The minimum viable agent: a loop and a small set of good tools.
| Stage | What It Adds | Tag |
|---|---|---|
| 00 | Bootstrap: SPM project, two-target layout, CI | 00-bootstrap |
| 01 | Agent loop + bash tool | 01-agent-loop |
| 02 | Tool dispatch: read_file, write_file, edit_file with path safety |
02-tool-dispatch |
| 03 | Todo tracking with nag reminder injection | 03-todo-write |
The features that make an agent feel like a usable product: context, memory management, and persistence.
| Stage | What It Adds | Tag |
|---|---|---|
| 04 | Subagents: recursive loop with fresh context | 04-subagents |
| 05 | Skill loading: .md files injected as tool results |
05-skill-loading |
| 06 | Context compaction: 3-layer strategy (micro, auto, manual) | 06-context-compaction |
| 07 | Task system: file-based CRUD with dependency DAG | 07-task-system |
| 08 | Background tasks: Task {} + actor-based notification queue |
08-background-tasks |
Two-target Swift Package Manager project:
Core is the library β API client, shell executor, agent loop, tools.
CLI is just the entry point. The executable is called agent.
Raw HTTP to POST https://api.anthropic.com/v1/messages using AsyncHTTPClient. Works on both macOS and Linux.
This project is not:
It's a staged exploration of coding-agent architecture β intentionally minimal, intentionally incomplete.
Process for shell command executiongit clone https://github.com/ivan-magda/swift-claude-code.git
cd swift-claude-code
# Set up your API key and model
cp .env.example .env
# Edit .env with your ANTHROPIC_API_KEY and MODEL_ID
swift build
swift run agent
tool_use, and tool_result workMIT
The hard part was picking when to trigger it. Too early and you're throwing away useful context. Too late and the model's already struggling. I ended up just using a simple token count β nothing clever, but it works.
And yeah, the Swift angle was genuinely fun. Defining tool schemas as Codable structs that auto-generate JSON schemas at compile time, getting compiler errors instead of runtime API failures is a huge win.
I've got some ideas inspired by this project. It's promising.