Skip to content
Skills Library
AI & agents · Tool integration

agent-cli

/agent-cli

Optional command line and MCP server for a macOS app, so agents, scripts, and other harnesses 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 "the agent should be able to use my app".

Repository
dsh-rev-eng ↗
Licence
MIT
Last repository change
31.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
11
Scripts
8
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 31.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 8 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/add-agent-cli.sh, scripts/check-agent-cli.sh, template/Agent/AgentCLI.swift, template/Agent/AgentCommands.swift, template/Agent/AgentCore.swift, template/Agent/AgentMCP.swift, template/Agent/AgentSocket.swift, template/Main.swift

What it does and when to use it

Optional command line and MCP server for a macOS app, so agents, scripts, and other harnesses 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 "the agent should be able to use my app".

Triggers from the description

the agent should be able to use my app
Original author description

Optional command line and MCP server for a macOS app, so agents, scripts, and other harnesses 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 "the agent should be able to use my app".

How it works

  1. CLI, MCP, or App Intents
  2. 1. List the commands
  3. 2. Add the files
  4. 3. Write the commands
  5. 4. Build and install
  6. 5. Test
  7. 6. Teach agents
  8. 7. MCP, when the user wants it
Original SKILL.md headings · 139 lines, 895 words
SKILL.md preview
---
name: agent-cli
description: Optional command line and MCP server for a macOS app, so agents, scripts, and other harnesses 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 "the agent should be able to use my app".
---

# 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
agent, bash --> tasks items add ...  --socket--> Tasks.app (runs the command, saves, redraws)
MCP client  --> tasks mcp            --socket--> same commands, same app
```

## CLI, MCP, or App Intents

| Way in | Who uses it | Ship it |
| --- | --- | --- |
| CLI | agents with a shell, scripts, people in Terminal | Always. Agents learn it from `--help`, and it costs no context until used |
| MCP (`tasks mcp`) | MCP 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
"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
"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 the target agent's skill or instruction file 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". dsh reads
skills from `~/.agents/skills/<cli-name>/SKILL.md` in every folder, and
other harnesses use their own skill directory. Add one line to the app's
`AGENTS.md`: "Drive the app with `<cli-name>`. See
`skills/<cli-name>/SKILL.md`."

Check: a fresh dsh session can do a real task with the CLI.

## 7. MCP, when the user wants it

For an MCP client with no shell, or to get one approval prompt per tool.
Give the client the full path to the binary inside the app: MCP clients do
not read the shell's `PATH`. The command is that path, the args are
`["mcp"]`. Most clients take a JSON entry under `mcpServers`:

```json
{ "mcpServers": { "<cli-name>": { "command": "/Users/<you>/Applications/<App>.app/Contents/MacOS/<App>", "args": ["mcp"] } } }
```

dsh: add the same entry as a stdio MCP client row in the harness profile,
then reload the session. A row that fails to connect starts the harness
without its tools, so check the harness logs first. More in
[teach-agents.md](teach-agents.md).

Check: the client lists the server as connected and one tool call returns
real data.

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 dsh session can do a real
task with it.
Files in this package (11)
  • SKILL.md 6 KB
  • rules.md 5 KB
  • teach-agents.md 4 KB
  • scripts/add-agent-cli.sh 3 KB
  • scripts/check-agent-cli.sh 3 KB
  • template/Main.swift 1 KB
  • template/Agent/AgentCLI.swift 10 KB
  • template/Agent/AgentCommands.swift 7 KB
  • template/Agent/AgentCore.swift 4 KB
  • template/Agent/AgentMCP.swift 3 KB
  • template/Agent/AgentSocket.swift 7 KB

Versions

RepositoryScoreLicence
This page · Stijnus/dsh-rev-eng100MIT
glebis/claude-skills100MIT
workflowsdiy/bama-light100MIT
daveebbelaar/bama100MIT
daveebbelaar/bawa100MIT
Zate/cc-plugins100MIT
MinnThikeTunn/Phan-Tee98MIT
nathanvale/side-quest-marketplace95MIT

Database snapshot: 13.11.2026 · package version 636f294feffd (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100click-to-mcp
    Auto-wrap any Click or typer Python CLI as an MCP server with zero code changes. Use this skill whenever the user wants to expose a CLI tool to an AI agent via MCP, needs to convert a Click/typer app into an MCP server, wants to run an existing CLI through an LLM, or asks about…
  • 96mcp-server-adoption
    Use when adopting an external MCP server or agent CLI.
  • 100computer-use-macos
    Operate macOS application UI through computer_use MCP and the Computer → App → Element SDK. Use when observing, clicking, or typing on a macOS MCP host, including a remote host. Select by target desktop, not the Agent machine.
  • 100computer-use-macos
    Operate macOS application UI through computer_use MCP and the Computer → App → Element SDK. Use when observing, clicking, or typing on a macOS MCP host, including a remote host. Select by target desktop, not the Agent machine.
  • 100duskcode
    Extending duskcode itself: add an agent, a skill or an MCP server. Use when asked to add or change dusk's agents, skills or MCP servers.
  • 100mcp-from-idea
    Turn a one-line idea (typed, voice note, WhatsApp text, or an existing repo) into a working, tested MCP server in minutes. Use when someone says "make an MCP for my idea", "create MCP tools for <project>", "expose <app> to Claude", or wants Claude to work with their product's data or rules.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.