Skip to content
Back to search

swift-coding-agent

SkillWorks with Claude CodeGitHub

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ivan-magda--swift-coding-agent/badge.svg)](/listings/ivan-magda--swift-coding-agent)

HTML

<a href="/listings/ivan-magda--swift-coding-agent"><img src="/api/listings/ivan-magda--swift-coding-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 143 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # swift-coding-agent
  2. Exploring the architecture of coding agents by rebuilding a Claude Code-style CLI from scratch in Swift.
  3. ![demo](demo.gif)
  4. ## Learning Series
  5. A 9-part learning series covers the build on [ivanmagda.dev](https://ivanmagda.dev).
  6. [Start the series →](https://ivanmagda.dev/posts/s00-bootstrapping-the-project)
  7. ## Why This Exists
  8. 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.
  9. My working theory: **coding agents benefit more from a small set of excellent tools and a tight loop than from large orchestration layers.**
  10. 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.
  11. This project rebuilds those mechanics in Swift, one stage at a time, to find out how little architecture the job needs.
  12. ## Hypothesis
  13. This project tests a few specific ideas about coding agents:
  14. - A small number of high-quality tools beats a large tool catalog
  15. - The model should do the heavy lifting; orchestration stays thin
  16. - Explicit task state improves reliability more than prompt-only planning
  17. - Controlled context injection matters more than persistent memory
  18. - Context compaction is a product feature, not a token optimization
  19. Each stage isolates one mechanism so I can see what it enables.
  20. ## The Agent Loop
  21. The whole thing boils down to one loop:
  22. ```swift
  23. func run(query: String) async throws -> String {
  24. messages.append(.user(query))
  25. while true {
  26. let request = APIRequest(
  27. model: model, system: systemPrompt, messages: messages, tools: Self.toolDefinitions
  28. )
  29. let response = try await apiClient.createMessage(request)
  30. messages.append(Message(role: .assistant, content: response.content))
  31. guard response.stopReason == .toolUse else {
  32. return response.content.textContent
  33. }
  34. var results: [ContentBlock] = []
  35. for block in response.content {
  36. if case .toolUse(let id, let name, let input) = block {
  37. let output = await executeTool(name: name, input: input)
  38. results.append(.toolResult(toolUseId: id, content: output, isError: false))
  39. }
  40. }
  41. messages.append(Message(role: .user, content: results))
  42. }
  43. }
  44. ```
  45. 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.
  46. ## Roadmap
  47. Git tags track progress. The roadmap has two phases: core mechanics first, then product-level features.
  48. ### Phase 1: Core Loop
  49. The minimum viable agent: a loop and a small set of good tools.
  50. | Stage | What It Adds | Tag |
  51. | ----- | ---------------------------------------------------------------------- | ------------------ |
  52. | 00 | Bootstrap: SPM project, two-target layout, CI | `00-bootstrap` |
  53. | 01 | Agent loop + bash tool | `01-agent-loop` |
  54. | 02 | Tool dispatch: `read_file`, `write_file`, `edit_file` with path safety | `02-tool-dispatch` |
  55. | 03 | Todo tracking with nag reminder injection | `03-todo-write` |
  56. ### Phase 2: Product Mechanics
  57. The features that make an agent feel like a usable product: context, memory management, and persistence.
  58. | Stage | What It Adds | Tag |
  59. | ----- | ------------------------------------------------------------ | ----------------------- |
  60. | 04 | Subagents: recursive loop with fresh context | `04-subagents` |
  61. | 05 | Skill loading: `.md` files injected as tool results | `05-skill-loading` |
  62. | 06 | Context compaction: 3-layer strategy (micro, auto, manual) | `06-context-compaction` |
  63. | 07 | Task system: file-based CRUD with dependency DAG | `07-task-system` |
  64. | 08 | Background tasks: `Task {}` + actor-based notification queue | `08-background-tasks` |
  65. ## Architecture
  66. Two-target Swift Package Manager project:
  67. **Core** is the library: API client, shell executor, agent loop, tools.
  68. **CLI** is the entry point. The executable is named `agent`.
  69. 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.
  70. ## Non-Goals
  71. This project is **not**:
  72. - A full Claude Code clone or drop-in replacement
  73. - A general-purpose multi-agent framework
  74. - Production-ready IDE tooling
  75. It's a staged exploration of coding-agent architecture. The gaps are deliberate.
  76. ## Tech Stack
  77. - **Swift 6.2** with strict concurrency
  78. - **AsyncHTTPClient** (SwiftNIO-based) for cross-platform HTTP + streaming SSE
  79. - **Foundation `Process`** for shell command execution
  80. - macOS 10.15+ / Linux
  81. ## Getting Started
  82. ```bash
  83. git clone https://github.com/ivan-magda/swift-coding-agent.git
  84. cd swift-coding-agent
  85. # Set up your API key and model
  86. cp .env.example .env
  87. # Edit .env with your ANTHROPIC_API_KEY and MODEL_ID
  88. swift build
  89. swift run agent
  90. ```
  91. ## References
  92. - [Anthropic Messages API](https://docs.anthropic.com/en/api/messages): the one endpoint the agent talks to
  93. - [Anthropic Tool Use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview): how tool definitions, `tool_use`, and `tool_result` work
  94. ## License
  95. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.