Skip to main content
skill CX Codex

agent-cli — Claude Code skill: what it does, how to install

agent-cli — a skill for Claude Code, Codex and Cursor that adds a command line and MCP server to a macOS app so agents can control it via a local socket.

MIT 1,000 installs ★ 1,933 updated 2026-11-05

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add daveebbelaar/bama --skill agent-cli -a claude-code
Open on GitHub

What agent-cli does

This skill equips macOS apps with a dedicated command line interface and MCP server so AI agents can perform actions inside active windows. Commands route through a private socket to trigger native functions while the UI updates instantly. Setup scripts copy the required core files and link the binary to the local bin directory.

A macOS app built on the template and working Swift toolchain are required beforehand. Configuration involves declaring commands with parameter hints, outputting compact JSON, and registering the MCP server for clients without shell access.

What it helps with

  • add a command line interface to a macOS app
  • register an MCP server for AI agent workflows
  • automate build verification and CLI tests
  • teach AI models the available app commands

Example prompts for the agent

  • Run the CLI setup script for the app folder
  • Verify the command set with the test script
  • Register the MCP server for Claude Desktop

How to install agent-cli

1Skills CLI (Vercel)

npx skills add daveebbelaar/bama --skill agent-cli -a claude-code

2Manually: put the files in place

~/.claude/skills/agent-cli/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/agent-cli/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about agent-cli

How to install agent-cli in Claude Code?

Run npx skills add daveebbelaar/bama --skill agent-cli -a claude-code and check ~/.claude/skills/agent-cli/SKILL.md.

What does agent-cli do?

It adds a command line and MCP server to a macOS application so AI agents can drive window actions and manage app data.

What is needed to run agent-cli?

A macOS app project, Swift compiler for builds, and ~/.local/bin added to your shell PATH are required.

Source text

SKILL.md · MIT
---
name: agent-cli
description: Optional command line and MCP server for a macOS app, so Claude Code, Codex, and scripts can drive it (list, add, change, search, act) through the running app. Use when the user wants agents to work with their app or its data, asks for a CLI, an MCP server, or automation for the app, or says "Claude should be able to use my app".
argument-hint: "<cli-name, like tasks or mail>"
---

# Agent CLI

Give the app a command line, so an agent can do everything a person can
do in the window: `tasks items add --title "Call the dentist"`. The app
binary is the CLI. Each command goes to the running app over a private
socket, runs there like a button press, and the window updates live.

```text
Claude Code --bash--> tasks items add ...  --socket--> Tasks.app (runs the command, saves, redraws)
Claude Desktop --MCP--> tasks mcp           --socket--> same commands, same app
```

## CLI, MCP, or App Intents

| Way in | Who uses it | Ship it |
| --- | --- | --- |
| CLI | Claude Code, Codex, scripts, people in Terminal | Always. Agents learn it from `--help`, and it costs no context until used |
| MCP (`tasks mcp`) | Claude Desktop and other clients with no shell | Optional. The same commands, one tool each. One line to register |
| App Intents | Siri, Spotlight, Shortcuts | Separate work. Agents cannot call them |

The CLI talks to the running app, never to the database file. Then there is
one writer, the app's checks and side effects run, and the window shows the
change at once. If the app is closed, the CLI opens it in the background.
Rules and reasons: [rules.md](rules.md).

## 1. List the commands

Read the user stories (`docs/stories/`). Write each thing a person does as
a command, `<noun> <verb>`, and mark it:

- **read**: `items list`, `items show`, `status`. Safe to run any time.
- **write**: `items add`, `items update`, `open`. Changes data, can be undone.
- **destructive**: `items delete`, `mail send`. Only reports what it would
  do until `--yes` is given.

Add `status` (is it running, what is open, counts) and `open <page>` (show
a page in the window), so an agent can see and steer the app.

Check: every M1 story has its commands, and each command is marked.

## 2. Add the files

```bash
"${CLAUDE_SKILL_DIR}/scripts/add-agent-cli.sh" <app-folder> <cli-name>
```

It copies `Sources/<App>/Agent/` (core, socket, CLI, MCP, example
commands) and `Main.swift`, moves `@main` to `Main.swift`, starts the socket
in the main view's `.task`, and makes `build.sh` link
`~/.local/bin/<cli-name>`. Apps not made from the template: do the same
by hand, following the script.

Check: the script printed "added the agent CLI", and `swift build` passes.

## 3. Write the commands

Replace the examples in `Agent/AgentCommands.swift`. Each command has a
name, a one-line summary, its params, a full example, its mark
(`readOnly` or `destructive`), and a `run` that uses the same model code
as the window's buttons. Never copy logic: call the function the button
calls.

- Every model an agent touches gets `var uuid: UUID = UUID()`. Commands
  show the first 8 characters as `id`, and accept any unique start of it.
- Results are small JSON objects: the fields an agent needs, not the
  whole model. Lists take `--limit` and `--offset`, and return `total`
  and `nextOffset`.
- Errors throw `AgentError` with a message that says how to fix it:
  "no item with id 3f2a. Run `tasks items list`".

All the rules: [rules.md](rules.md).

Check: `<cli-name> help` lists every command from step 1, and
`<cli-name> help <command>` shows its params and example.

## 4. Build and install

```bash
./build.sh
<cli-name> help
```

`build.sh` installs the app and links `~/.local/bin/<cli-name>` to the
binary inside it, so the CLI always matches the app. If the shell cannot
find it, add `~/.local/bin` to `PATH` in `~/.zshrc`.

Check: `<cli-name> --version` prints the app's version.

## 5. Test

```bash
"${CLAUDE_SKILL_DIR}/scripts/check-agent-cli.sh" <cli-name>
```

It starts a test copy of the app on a temporary database, checks help,
JSON output, error codes, every read command, and the MCP tool list, then
quits the test copy. Then run each write command once by hand, with
`APP_STORE=/tmp/<App>-test.store`, and look at the window: the change shows
without a reload.

Check: the script prints `PASS agent CLI`.

## 6. Teach agents

Write `.claude/skills/<cli-name>/SKILL.md` in the app's repo from
[teach-agents.md](teach-agents.md): what the app is, the safety rules,
the main commands, and "run `<cli-name> help` for the rest". To use the
app from any folder, also copy it to `~/.claude/skills/<cli-name>/`. Add
one line to the app's `CLAUDE.md`: "Drive the app with `<cli-name>`. See
`.claude/skills/<cli-name>/SKILL.md`."

Check: a fresh `claude -p "List my starred items with <cli-name>"` finds
the CLI and answers from real data.

## 7. MCP, when the user wants it

For Claude Desktop, or to get one approval prompt per tool:

```bash
claude mcp add --scope user <cli-name> -- ~/Applications/<App>.app/Contents/MacOS/<App> mcp
codex mcp add <cli-name> -- ~/Applications/<App>.app/Contents/MacOS/<App> mcp
```

Claude Desktop: add it to `~/Library/Application Support/Claude/claude_desktop_config.json`
under `mcpServers`, with the full path and `"args": ["mcp"]`. More in
[teach-agents.md](teach-agents.md).

Check: `claude mcp list` shows the server as connected.

Done when every command from step 1 runs through the CLI against the
running app, `check-agent-cli.sh` prints `PASS agent CLI`, the app's repo
has the agent skill from step 6, and a fresh Claude Code session can do a
real task with it.

© daveebbelaar · MIT · daveebbelaar/bama

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set21

The whole set →
research This Claude Code skill researches a macOS app idea before development. It sends parallel subagents to compare products, user feedback, features, and macOS APIs. CX Codex +1 1,000installs improve-loop improve-loop — a Claude Code skill that works through a macOS app’s stories in docs/STORIES.md. It builds the app, checks screen snapshots against references, and commits completed work. CX Codex +1 1,000installs build-and-verify build-and-verify — a Claude Code skill that builds SwiftUI macOS apps and checks page snapshots in light and dark appearance. The agent invokes it after UI changes, failed builds, or requests to run or inspect the app. CX Codex +1 1,000installs performance performance — a skill for Claude Code that measures CPU, memory, and energy usage in macOS apps. It identifies causes of freezes and helps offload tasks from the main thread to the GPU. CX Codex +1 1,000installs improve-architecture The improve-architecture Claude Code skill reviews a macOS Swift codebase and plans refactors that preserve existing behavior. It activates before a major feature, at a milestone, or when bugs keep returning in one area. CX Codex +1 1,000installs app-brief The app-brief skill for Claude Code and Cursor generates a one-page docs/BRIEF.md file for a new macOS app before writing code. CX Codex +1 1,000installs design-from-app design-from-app — a Claude Code skill that rebuilds any app interface as a native SwiftUI design kit using reference screenshots. CX Codex +1 1,000installs os-integrations The os-integrations Claude Code skill maps macOS APIs to system-level features and their required permissions. It applies when adding global shortcuts, screen capture, or controls for other apps’ windows. CX Codex +1 1,000installs

Project sponsors

Companies that keep this analytics open