Swift Claude Code

swift-claude-code

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


Learning Series

A complete 9-part learning series is available on [ivanmagda.dev](https://ivanmagda.dev).

[Start the series →](https://ivanmagda.dev/posts/s00-bootstrapping-the-project)

Why This Exists

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.

Hypothesis

This project tests a few specific ideas about coding agents:

• A small number of high-quality tools beats a large tool catalog
• The model should do most of the heavy lifting — thin orchestration, not thick
• Explicit task state improves reliability more than prompt-only planning
• Controlled context injection matters more than persistent memory
• Context compaction is a product feature, not just a token optimization

Each stage is designed to isolate one mechanism and see what it enables.

The Agent Loop

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.

Roadmap

Progress is tracked via git tags. The roadmap is split into two phases —