swift-claude-code

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

Learning Series

A 9-part learning series covers the build on ivanmagda.dev.

Start the series →

Why This Exists

Claude Code works better than most coding agents I've used, and I think the reason is restraint. I studied its tool surface and traced its loop to isolate which design choices do the work.

My working theory: coding agents benefit more from a small set of excellent tools and a tight loop than from large orchestration layers.

Claude Code ships few tools, and the ones it has are simple: a search tool, a file editor. They work well. The system trusts the model and skips the scaffolding most agents pile on.

This project rebuilds those mechanics in Swift, one stage at a time, to find out how little architecture the job needs.

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 the heavy lifting; orchestration stays thin
• 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 a token optimization

Each stage isolates one mechanism so I can 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 fixed; the tools vary. Every stage adds entries to the tool handler dictionary and injection points before the API call, but the loop body itself stays identical.

Roadmap

Git tags track progress. The roadmap has two phases: core mechanics first, then product-level features.

Phase 1: Core Loop

The minimum viable agent: a loop and a small set of good tools.

Phase 2: Product Mechanics

The features that make an agent feel like a usable product: context, memory management, and persistence.

Architecture

Two-target Swift Package Manager project:

Core is the library: API client, shell executor, agent loop, tools.

CLI is the entry point. The executable is named agent.

The agent talks to POST https://api.anthropic.com/v1/messages over raw HTTP, built on AsyncHTTPClient. It runs on macOS and Linux.

Non-Goals

This project is not:

• A full Claude Code clone or drop-in replacement
• A general-purpose multi-agent framework
• Production-ready IDE tooling

It's a staged exploration of coding-agent architecture. The gaps are deliberate.

Tech Stack

• Swift 6.2 with strict concurrency
• AsyncHTTPClient (SwiftNIO-based) for cross-platform HTTP + streaming SSE
• Foundation Process for shell command execution
• macOS 10.15+ / Linux

Getting Started

git 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

References

• Anthropic Messages API: the one endpoint the agent talks to
• Anthropic Tool Use: how tool definitions, tool_use, and tool_result work

License

MIT