An open API service indexing awesome lists of open source software.

https://github.com/ivan-magda/swift-coding-agent

A Swift reimplementation of a Claude Code-style coding agent, built stage by stage to explore what makes coding agents work
https://github.com/ivan-magda/swift-coding-agent

agentic-ai ai-agent anthropic claude-code cli coding-agent developer-tools swift swift-concurrency swift-package-manager

Last synced: 4 months ago
JSON representation

A Swift reimplementation of a Claude Code-style coding agent, built stage by stage to explore what makes coding agents work

Awesome Lists containing this project

README

          

# swift-coding-agent

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

![demo](demo.gif)

## Learning Series

A 9-part learning series covers the build on [ivanmagda.dev](https://ivanmagda.dev).

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

## 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:

```swift
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.

| 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 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](https://github.com/swift-server/async-http-client). 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

```bash
git clone https://github.com/ivan-magda/swift-coding-agent.git
cd swift-coding-agent

# 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](https://docs.anthropic.com/en/api/messages): the one endpoint the agent talks to
- [Anthropic Tool Use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview): how tool definitions, `tool_use`, and `tool_result` work

## License

MIT