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 — core mechanics first, then product-level features.

Phase 1 — Core Loop

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 |

Phase 2 — Product Mechanics

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 |

Architecture

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.

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 — intentionally minimal, intentionally incomplete.

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 single endpoint the entire agent talks to
• Anthropic Tool Use — how tool definitions, tool_use, and tool_result work

License

MIT