A lightweight coding agent for your terminal, written in Swift. Reads your code, fixes bugs, runs tests and automates dev tasks with the model you choose — asking before it changes anything. Chat with it, pipe into it, or run it in CI.
Built on SwiftAgentKit, the open-source engine behind Naseem, the AI agent for Mac — about 2,700 lines on top of it.
Want it in a Mac app? Naseem is the full desktop agent: it works in your projects, files and apps, and has memory and skills. Naseem Pro adds the iOS Simulator, Mac app control, sub-agents and a reviewer.
sakand Naseem share project notes and skills, so you can switch between the terminal and the app at any time. See how they work together ↓
A real session, as recorded (kimi-k2.6:cloud through Ollama; the folder's path shortened). It opens with what the agent has, then asks before each change:
╭─ sak 0.3.0-alpha ────────────────────────────────────────────────────────────────────────────────────╮
│ ███████ █████ ██ ██ │ Tools │
│ ██ ██ ██ ██ ██ │ files list_dir, search_files, read_file, edit_file, │
│ ███████ ███████ █████ │ write_file │
│ ██ ██ ██ ██ ██ │ shell run_shell │
│ ███████ ██ ██ ██ ██ │ web web_search, fetch_url │
│ a coding agent for your terminal │ │
│ │ │
│ model kimi-k2.6:cloud │ │
│ via Ollama │ │
│ folder ~/projects/DateKit │ │
│ mode asks before changes │ │
│ window 262K tokens │ │
│ config ~/.config/sak/.env │ │
│ │
│ 8 tools · 0 skills · /help for commands · Ctrl-C stops a request · Ctrl-D quits │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────╯
── kimi-k2.6:cloud · ctx 0/262K ▱▱▱▱▱▱▱▱▱▱ 0% · DateKit · asks before changes ──────────────────────────
❯ the date parser test fails — find out why and fix it
→ list_dir path=.
✓ Package.swift ⏎ Sources/ ⏎ Tests/
→ list_dir path=Sources
✓ Core/
→ list_dir path=Tests
✓ CoreTests/
→ list_dir path=Sources/Core
✓ DateParser.swift
→ list_dir path=Tests/CoreTests
✓ DateParserTests.swift
→ read_file path=Sources/Core/DateParser.swift
✓ import Foundation ⏎ ⏎ /// Parses the timestamps our server sends, e.g. "2025-12-29 14:30". ⏎ public…
→ read_file path=Tests/CoreTests/DateParserTests.swift
✓ import XCTest ⏎ @testable import Core ⏎ ⏎ final class DateParserTests: XCTestCase { ⏎ func test…
The bug is in DateParser.swift: the format string uses hh (12-hour clock) but the timestamp uses 14:30, which requires HH (24-hour clock).
? allow edit_file new_text= formatter.dateFormat = "yyyy-MM-dd HH:mm" old_text= formatter.dateFormat = "yyyy-MM-dd hh:mm" path=Sources/Core/DateParser.swift
[y]es [n]o [a]lways for edit_file [A] everything this session › y
→ edit_file Sources/Core/DateParser.swift (1 → 1 lines)
✓ Replaced 1 occurrence in Sources/Core/DateParser.swift.
? allow run_shell command=swift test 2>&1
[y]es [n]o [a]lways for run_shell [A] everything this session › y
→ run_shell command=swift test 2>&1
✓ exit 0 ⏎ [0/1] Planning build ⏎ Building for debugging... ⏎ [0/3] Write sources ⏎ [1/3] Write swift-…
Fixed. The DateParser used hh:mm (12-hour clock), so 14:30 couldn't be parsed. Changed to HH:mm (24-hour clock). Tests now pass.
── kimi-k2.6:cloud · ctx 1.1K/262K ▰▱▱▱▱▱▱▱▱▱ 0% · DateKit · asks before changes ───────────────────────
❯
- Reads and changes code in one folder: lists, searches and reads files, edits them in place (search-and-replace, never a rewrite you didn't see), writes new ones, runs build and test commands, fetches web pages, and searches the web with a Tavily key. File tools can't leave the folder you started in.
- Asks before anything that changes something — an edit, a shell command, an MCP tool that acts. Reads never ask. One keystroke approves a tool, a whole MCP server, or everything for the session.
- Works with your MCP servers: a browser (chrome-devtools), a database, a docs server — from
mcp.jsonor, if you use Naseem, the servers you already set up there. - Any model you have: Ollama (local or cloud), Anthropic, OpenAI, Gemini, OpenRouter; switch mid-conversation and keep the context.
- Runs unattended: one request from a script or CI, JSON out, exit codes that mean something;
--read-onlyfor reviews,--autofor pipelines you trust. - Remembers per folder:
sak -ccontinues the last conversation in this folder; with Naseem it shares project notes and skills.
- Where the work already is. Build output, test failures, git — pipe them straight in:
swift test 2>&1 | sak "why does this fail?". No copy-paste into a chat window. - Small prompts, fast turns. sak sends the model a short system prompt, seven tool schemas and the files it actually read — not a transcript of everything. On the same tasks and the same model, that was a third to a quarter of the tokens of the larger agents and correspondingly faster (see Measured).
- Scriptable. It composes like any Unix tool: pre-commit hooks, CI steps, a nightly review, or another agent calling it.
- Readable. About 2,700 lines of Swift on a public engine: you can see exactly what runs in your folder.
- Fix this failing test — the session above: find, read, edit, run the test, report.
- Review before I commit —
git diff --cached | sak --read-only "bugs? one paragraph". - Explain this codebase to me —
sak -r "how does the sync layer work? files and flow". - Small, well-defined changes — add a flag, rename safely, write the missing test, update a README from the code.
- Front-end checks with a browser — with chrome-devtools: open the local page, read the console, click through a flow.
- Batch work in CI — label issues, lint prose, generate a changelog, each as one
sak --jsoncall.
Not (yet) a good fit: a multi-day refactor across a large codebase, work that needs a plan you review first, or anything where the tests themselves are the question — see Status and limits.
Requires macOS 14+ and Swift 6.2 (Xcode 26).
git clone https://github.com/ayman3000/sak.git
cd sak
make install # builds a release binary and links it to /usr/local/bin/sakIf /usr/local/bin isn't writable, run sudo make install, or install somewhere else with make install PREFIX=~/.local. make install links to the binary inside the clone, so keep the folder. make uninstall removes the link.
make smoke runs three real requests (a question, a read-only review of this repo, an edit in a temporary folder) and prints their turns, tool calls and tokens — the quick check after changing sak or SwiftAgentKit.
Then add your keys (only the ones you use):
mkdir -p ~/.config/sak && cp .env.example ~/.config/sak/.env && open -e ~/.config/sak/.envWith no keys set, sak uses Ollama on your Mac. The default model, kimi-k2.6:cloud, is an Ollama cloud model, so it needs ollama signin first. To stay fully local, pick a model you've pulled, such as sak -m llama3.2, or choose one with /model.
sak # chat in the current folder
sak "add a --verbose flag to the CLI" # one request, then exit
sak -c # continue this folder's last chat| Option | What it does |
|---|---|
-P, --provider <name> |
use a provider: ollama, anthropic, openai, gemini, openrouter |
-m, --model <name> |
use a model |
-r, --read-only |
no edit or shell tools |
-y, --yes, --auto |
auto mode: edits, shell commands and MCP tools run without asking (SAK_AUTO=1 in .env does the same for every run) |
-c, --continue |
continue this folder's last chat |
--json |
print one JSON result (for scripts) |
-q, --quiet |
print only the answer, no progress |
--turns <n> |
the maximum number of agent turns per request (default 30) |
-v, --version · -h, --help |
version · help |
Type / and a menu of commands opens under the prompt. It narrows as you type:
❯ /p
❯ /provider [name] [model] switch provider: ollama, anthropic, openai, gemini, openrouter
/providers list providers and which ones have a key
/mcp the MCP servers from mcp.json and their tools
/help this list
| Key | In the menu |
|---|---|
| ↓ ↑ | move the highlight (it wraps) |
| Enter | run the highlighted command — /mo + Enter runs /model |
| Tab | put it on the line, ready for its arguments |
| Esc | close the menu and keep what you typed |
| Command | What it does |
|---|---|
/model |
show the model and pick another from a numbered list |
/model claude-opus-5-5 |
switch model by name |
/provider anthropic |
switch provider: ollama, anthropic, openai, gemini, openrouter |
/providers |
which providers are ready, and which need a key |
/tools · /mcp · /skills · /notes |
what the agent can use and knows |
/yes |
toggle auto-approve for edits and shell commands |
/usage |
tokens and tool calls so far |
/save · /resume |
save and reload conversations |
/clear · /help · /exit |
fresh conversation · this list · quit |
Switching model keeps the conversation, so you can plan with one model and finish with another. Your choice is remembered for next time.
Above each prompt, a line shows the model, how full the context window is (the bar turns yellow at 60% and red at 85%), the folder and branch, and the mode.
With no menu open, ↑/↓ go through your history; Ctrl-R searches it, Ctrl-C stops a running request, Ctrl-D quits. End a line with \ to keep typing on the next. Text in any language works at the prompt, whatever the terminal's LANG.
Pipe anything in. Progress goes to stderr, so stdout has only the answer:
swift test 2>&1 | sak "why does this fail? one paragraph"
git diff --staged | sak "review this diff for bugs" > review.md--read-only removes the edit and shell tools — safe to run on any repo. --json prints one result object:
sak --read-only --json "list every TODO with its file and line"{
"ok": true, "exit_code": 0,
"provider": "anthropic", "model": "claude-sonnet-5",
"response": "…", "turns": 4, "tool_calls": 3, "tool_errors": 0,
"denied_tools": [], "elapsed_seconds": 12.4, "context_window": 200000,
"usage": { "input_tokens": 18234, "output_tokens": 612, "cached_tokens": 9000 }
}When nobody is there to approve a change, sak stops instead of trying something else, and exits with code 3. Pass -y (or --auto) to allow changes in a pipeline you trust; another agent driving sak — Claude Code calling sak --auto --json "…", say — gets one JSON result back and never a prompt.
| Exit code | Meaning |
|---|---|
| 0 | done |
| 1 | error (model or network) |
| 2 | bad usage or missing API key |
| 3 | a tool needed approval and was denied |
| 4 | hit the turn limit (--turns) |
| 130 | stopped with Ctrl-C |
sak is a command, so any agent that can run commands can use it as a worker: a second opinion, a parallel task in another folder, or a cheap model doing the mechanical part.
# Claude Code (or anything with a shell) asks sak for a read-only review and gets one JSON object back
sak --read-only --json -q "Review this repository for obvious bugs; list file:line and a sentence each."
# a trusted pipeline: let sak make the change, with the result and exit code to act on
SAK_AUTO=1 sak --json -q "Add a --version flag that prints the version from Package.swift, with a test."Rules that make this safe to automate: --read-only has no edit or shell tools at all; without --auto/SAK_AUTO=1 a change that needs approval stops (exit 3) instead of trying another way; --json always returns one object with ok, exit_code, response, usage, and never a prompt; nothing is read from stdin when stdin is idle.
A pre-commit review, for example:
# .git/hooks/pre-commit
git diff --cached | sak --read-only -q "Reply BLOCK and the reason if this diff has an obvious bug, else OK" | grep -q '^OK'sak reads KEY=value files, like python-dotenv. The first place that has a key wins:
- the environment (
export ANTHROPIC_API_KEY=…) ./.envin the folder you runsakin~/.config/sak/.env
| Key | For |
|---|---|
ANTHROPIC_API_KEY · OPENAI_API_KEY · GEMINI_API_KEY · OPENROUTER_API_KEY |
the cloud providers |
TAVILY_API_KEY |
turns on the web_search tool (tavily.com, free tier) |
SAK_PROVIDER · SAK_MODEL |
the default provider and model |
OLLAMA_HOST |
an Ollama server that isn't localhost:11434 |
SAK_AUTO=1 |
auto mode for every run, same as -y — for a tool that drives sak and can't answer prompts |
SAK_NASEEM=0 |
don't read Naseem's notes, skills and MCP servers |
SAK_CONFIG_DIR |
use another folder than ~/.config/sak (.env, mcp.json, skills, sessions) |
Keys from .env files aren't put in the environment, so a shell command the agent runs doesn't inherit them — but a shell command can still read the file, as you could. Keys you export in your shell are inherited like any program's environment. Keep keys in ~/.config/sak/.env rather than a project's .env: the agent's file tools reach your project, not your home folder.
Tools from MCP servers join the agent's own. Put them in ~/.config/sak/mcp.json (every project) or ./.sak/mcp.json (one project), in the same shape Claude Code and Claude Desktop use, so a config can be pasted across:
{ "mcpServers": {
"chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest", "--isolated"] },
"docs": { "url": "https://example.com/mcp" } } }If you use Naseem, its enabled MCP servers come along automatically — read from its settings, nothing written back — except servers that need a sign-in (their tokens live in Naseem); SAK_NASEEM=0 turns that off, and a same-named entry in mcp.json wins.
A tool the server marks read-only runs like read_file; any other asks first, like an edit (-y and /yes apply). --read-only keeps only the read-only ones. /mcp lists the servers and their tools; the banner says how many tools came from where. Every server adds its tool schemas to every request — a browser server is a few thousand tokens per call — so list the ones you use.
- File tools only reach the folder you started
sakin (paths are resolved, symlinks included, before the check). - Shell commands can reach anything your user can — that is why each one asks first, unless you pass
-yor turn on/yes. Edits and MCP tools that change things ask too. At the prompt:yonce,aalways for that tool,sfor every tool of that MCP server,Afor everything, all for this session. --read-onlyhas no edit or shell tools at all.
If you use Naseem, sak shares what it knows:
- Project notes. Naseem keeps
naseem/project.md,rules.md,roadmap.mdandjournal.mdin a project.sakfollows those rules, sees the open roadmap items, and adds a line to the journal when it changed something (in Naseem's own[build]format, markedsak:) — so Naseem knows what you did in the terminal, and the other way round. A question answered leaves no entry. - Skills. Naseem's skills are available in
saktoo. Skillssaklearns go to~/.config/sak/skills; it never changes Naseem's. - MCP servers. The servers you enabled in Naseem work in
saktoo (see MCP servers).
A typical day: plan a feature with Naseem, fix a failing test with sak in the terminal, then let Naseem pick up from the journal. Neither tool loses track of what the other did.
sak |
Naseem | |
|---|---|---|
| Where | the terminal, scripts, CI | a native Mac app |
| Models | Ollama, Anthropic, OpenAI, Gemini, OpenRouter | those and more, with a reviewer and a helper model |
| Code, files, shell, web | ✓ | ✓ |
| Project notes and skills | shared: reads them, journals its work | full memory, lessons, skills |
| Workflows on a schedule, Telegram | — | ✓ |
| iOS Simulator, Mac app control, sub-agents | — | Pro |
For the iOS Simulator, Mac app control, sub-agents and a reviewer in a real Mac app, get Naseem Pro.
sak is about 2,700 lines of Swift on top of SwiftAgentKit, and it's meant to be read as an example of a real agent. Start at Sources/sak/Session.swift: it builds the agent, its tools and its approval prompt.
SwiftAgentKit the agent loop, tools, memory, skills
│
┌────────┴────────┐
sak Naseem sak: Terminal.swift (prompt, Ctrl-C),
terminal Mac app Welcome.swift, SlashMenu.swift (the panel, the / menu),
│ │ Session.swift (agent, tools, approvals),
└────────┬────────┘ ProjectContext.swift (the shared notes and skills)
│
naseem/ notes · skills in your project folder and ~/Library/Application Support/Naseem
The engine's own examples are in SwiftAgentKit/Examples.
On an internal benchmark of six coding tasks (Swift, Python, TypeScript, one React app from scratch; hidden tests grade the result), run the same day on the same model:
| kimi-k2.6:cloud (Ollama Cloud, no prompt caching) | Claude Haiku 5.5 (Anthropic API) | |
|---|---|---|
| sak | 10/12 pass · 1,013 s total · 89K tokens in (median) | 6/6 · 274 s · 599K in (total) |
| Claude Code | 10/12 · 2,691 s · 308K in — different day | 5/6 · 356 s · 2.27M in |
| Hermes | 12/12 · 4,173 s · 155K in — different day | — |
On the three tasks re-run the same day on kimi, sak was 1.2–2× faster than Claude Code and Hermes with a third to a quarter of the tokens; with Anthropic's prompt caching the time gap narrows to about 1.3× and the token gap stays. Small tasks, one person's harness, your mileage will vary — the point is the shape: fewer tokens per call, fewer calls. Both failures were the model editing a protected test or papering over a test environment; the prompt now forbids the first.
sak is alpha (0.3.0-alpha). Commands, flags and the --json fields may change before 1.0. CI builds it and runs its tests on every change; make smoke runs three real requests against a model. Tested day to day with Ollama; Anthropic and OpenAI through the benchmark; Gemini and OpenRouter use the same code with less real-world time.
What it doesn't do yet, honestly:
- No plan step. It reads, then acts; there is no plan you approve first. For a big change, ask for the plan as a question (
-r) before asking for the change. - No sandbox for shell commands. They run as you, after you approve them (or always, with
--auto). File tools are confined to the folder; shell commands are not. - Keys in
.envare readable by a shell command you approve, like any file. Keep keys in~/.config/sak/.env, not in a project. - It can still touch tests you asked it to make pass — the prompt forbids it, models sometimes do it anyway. Protected tests in a hidden copy are the real guard.
- One conversation per folder with
-c; no branching, no sharing across machines. - Tab completes commands, not file names, and the
/menu hasn't been tried with Ctrl-Z or while the window is being resized. - Tokens, not dollars:
/usageshows counts, not cost. - MCP servers cost tokens: every server's tool schemas ride along on every request; a browser server is a few thousand tokens per call. List the ones you use.
- macOS only, Swift 6.2 to build; no Homebrew formula yet (coming).
Please report anything that breaks.
MIT — see LICENSE.