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
- Host: GitHub
- URL: https://github.com/ivan-magda/swift-coding-agent
- Owner: ivan-magda
- License: mit
- Created: 2026-03-10T18:58:56.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2026-06-26T11:17:42.000Z (5 months ago)
- Last Synced: 2026-07-11T03:00:42.210Z (4 months ago)
- Topics: agentic-ai, ai-agent, anthropic, claude-code, cli, coding-agent, developer-tools, swift, swift-concurrency, swift-package-manager
- Language: Swift
- Homepage: https://ivanmagda.dev/posts/s00-bootstrapping-the-project/
- Size: 371 KB
- Stars: 173
- Watchers: 3
- Forks: 10
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-swift - swift-coding-agent - A terminal coding agent with subagents and context compaction. (Libs / AI)
- awesome-swift - swift-coding-agent - A terminal coding agent with subagents and context compaction. (Libs / AI)
README
# swift-coding-agent
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](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