Put your Mac to work.

Settings → General

General

Controls startup, appearance, Dock behavior, displays, voice input, and optional screen context.

Settings → Dock Items

Dock Items

Settings → Shortcuts

Keyboard Shortcuts

Enable or disable Kuttle’s global keyboard commands. The default ⌘⇧D opens and focuses the command field on the display under the pointer. Global shortcuts require Accessibility permission and are not installed when that permission is unavailable.

Settings → Agents

Agents

Agents define which model handles a request, what specialist knowledge it receives, and when the main @kuttle orchestrator should route work to it. Use @kuttle for a goal that may need planning, tools, or multiple capabilities. Use a named trigger such as @research when you already know which specialist should handle the request.

Create an agent profile

1. Open Kuttle Settings → Agents → Agent Profiles.
2. Select Add Agent. Kuttle opens a sheet for the new file-backed worker.
3. Enter a unique trigger such as @research. Kuttle adds a missing @, converts the trigger to lowercase, and uses its safe form as the profile and folder identifier.
4. Add an optional description that states the specialist's purpose, for example, Researches products, verifies claims, and returns a source-backed brief. When no custom SKILL.md is uploaded, Kuttle appends this purpose to the generated skill.
5. Choose Text for analysis, writing, and structured responses, or Image generation for visual creation and editing.
6. Choose a provider and model. For image agents, also choose default aspect ratio, size, and OpenAI quality when applicable. Values written in the prompt, such as 16:9 or 4K, override image defaults.
7. Optionally choose an existing Markdown file for AGENTS.md, SKILL.md, or MEMORY.md. If omitted, Kuttle generates safe starter files; all three remain editable later.
8. Select Add Agent. The worker is enabled immediately and appears in Agent Profiles. Use Edit Files on its profile to review or change its context.

Choose a useful name and trigger

Name an agent for the role or outcome it owns, not for the underlying model. Models can change without changing what the agent means to the user.

Triggers must be unique. Prefer lowercase words, hyphens, or underscores with no spaces: @invoice-review, @finance, or @product_research. The visible display name can be more natural, such as Invoice Review.

Add provider credentials

A profile cannot call a remote model until its provider has an enabled credential. Kuttle supports the providers shown in the current build: OpenAI, Anthropic, Gemini, and OpenRouter.

1. Create an API key in the provider's console: OpenAI, Anthropic, Gemini, or OpenRouter. Review that provider's billing and data controls first.
2. Open Kuttle Settings → Agents → API Keys.
3. Turn on the switch for the provider Kuttle may use.
4. Paste the key into that provider's secure field, then select Save to Keychain.
5. Confirm that the row shows Stored. Kuttle stores the secret in macOS Keychain; it is not written to agent Markdown, settings JSON, task traces, or memory.
6. Return to Agent Profiles and select that provider and one of its available models for the orchestrator or worker.
7. Test with a harmless prompt such as @research summarize why leaves change color in three bullets. If the key is missing or disabled, Kuttle reports which provider must be configured.

What the agent files do

Kuttle loads these files at the start of every conversation. Provider and model settings remain controlled by Settings, even if Markdown claims otherwise. Live adapters, permissions, allowed folders, and host policy also take priority over file text.

AGENTS.md: startup and memory policy

This file is read first. Keep it stable and short. It should tell the runtime which files to read, identify the trigger and role, and define what is safe to preserve in memory. It is not the place for API keys, model selection, a long persona, or detailed domain procedures.

# Research Agent Index

This file is the startup table of contents and is read first.

## Read order
1. Read `AGENTS.md` for startup and memory policy.
2. Read `SKILL.md` before planning or accepting routed work.
3. Read relevant `MEMORY.md` entries for durable context.

## Runtime profile
- Trigger: `@research`
- Role: worker
- Agent type: text
- Provider and model are selected in Kuttle Settings.

## Saving memory
Write to `MEMORY.md` only after a successful result reveals durable,
reusable knowledge. Never save credentials, raw conversations, temporary
TODOs, debugging logs, or short-lived task state.

SKILL.md: routing and operating contract

The orchestrator uses this file's description and declared capabilities to decide whether the specialist fits a goal. Be concrete about when to use the agent, its expected inputs and output, its workflow, and its boundaries. A vague skill causes poor routing.

---
name: Research
description: Researches a defined topic, verifies important claims, and
  returns a concise source-backed brief with facts separated from inference.
---

# Research Skill

## Use when
- The user asks to compare products, vendors, sources, or claims.
- The result needs evidence, links, or a decision-ready brief.

## Inputs
- A question, topic, or comparison criteria.
- Optional active-browser, selected-file, or user-supplied context.

## Capabilities
- Analyze supplied context and approved source results.
- Organize findings, disagreements, risks, and open questions.
- Produce a brief, comparison table, or source list.

## Workflow
1. Restate the decision or outcome being researched.
2. Use only enabled adapters and approved tools needed for the task.
3. Verify consequential claims with independent evidence when possible.
4. Separate observed facts, source claims, and model inference.
5. Return the requested artifact and identify remaining uncertainty.

## Constraints
- Never invent a source, quote, completed action, or file modification.
- Do not bypass adapter permissions, allowed folders, or approval policy.
- Do not store credentials or user secrets in any agent file.

## Output
- Lead with the answer.
- Cite sources next to supported claims.
- End with material uncertainty or a concrete next action.

MEMORY.md: durable reusable knowledge

Memory is knowledge, not instructions. Save stable preferences, decisions, recurring constraints, historical context, and reusable lessons only when they will improve future work. Explain why each item matters and date decisions that may become stale.

# Research Memory

## User preferences
- The user wants decision briefs to lead with the recommendation and keep
  supporting evidence under 600 words. This reduces review time.

## Product decisions
- 2026-07-31: Prefer native macOS integrations over browser automation when
  both expose the required capability. Native adapters are easier to audit.

## Known constraints
- Customer documents may be read only from folders approved in Settings.
- Never include credentials, private tokens, or raw email bodies in memory.

## Reusable knowledge
- Distinguish a configured capability from a verified completed action.
  Report completion only after the host adapter returns success.

Manage agent storage

1. Open Kuttle Settings → Agents → Agent Storage.
2. Select Open to inspect the current root or Choose Folder to relocate it. Select Use Default to return to ~/kuttle/agents.
3. Keep one folder per profile identifier. For @research, Kuttle uses a layout like the example below.
4. Edit files from Finder or choose Edit Files on the profile. Save valid UTF-8 Markdown.
5. Start a new conversation to guarantee the updated files are loaded from the beginning. Existing responses are not retroactively replanned.

~/kuttle/agents/
├── agent/
│   ├── AGENTS.md
│   ├── SKILL.md
│   └── MEMORY.md
└── research/
    ├── AGENTS.md
    ├── SKILL.md
    └── MEMORY.md

How routing works

Troubleshooting agents

Settings → Integrations

Integrations

Integrations are adapters. Enabling one exposes only its declared capabilities to planning; the planner cannot invent an unconfigured connection.

Settings → Tools

Tools

Tools extend what agents can do. Installation and execution remain host-controlled; the model receives tool descriptions and schemas, not unrestricted access to source code or your computer.

Create a Python tool

A tool is one folder with a manifest and one Python entry point. The folder name can be descriptive; the manifest id is the stable identifier Kuttle uses for planning and execution.

my-tool/
├── tools.json
└── main.py

tools.json structure

{
  "id": "word_count",
  "name": "Word Count",
  "description": "Counts words and characters in supplied text.",
  "author": "Your name",
  "version": "1.0.0",
  "dependencies": {},
  "inputSchema": {
    "type": "object",
    "properties": {
      "text": {
        "type": "string",
        "description": "Text to analyze"
      }
    },
    "required": ["text"],
    "additionalProperties": true
  },
  "capabilities": {
    "files": [],
    "network": {
      "enabled": false,
      "domains": [],
      "methods": [],
      "maxResponseBytes": 0
    },
    "secrets": [],
    "subprocesses": false
  },
  "env": []
}

"description": "Counts words and characters in supplied text."

"inputSchema": {
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "Text to analyze",
      "minLength": 1,
      "maxLength": 10000
    },
    "mode": {
      "type": "string",
      "enum": ["short", "detailed"],
      "default": "short"
    }
  },
  "required": ["text"],
  "additionalProperties": true
}

"dependencies": {
  "requests": "2.32.3",
  "python-dateutil": "2.9.0"
}

"dependencies": [
  "requests==2.32.3",
  "python-dateutil>=2.9.0"
]

"capabilities": {
  "files": [
    {"selector": "user-selected", "mode": "read"},
    {"selector": "run-output", "mode": "write"}
  ],
  "network": {
    "enabled": false,
    "domains": [],
    "methods": [],
    "maxResponseBytes": 0
  },
  "secrets": [],
  "subprocesses": false
}

"env": ["WEATHER_API_KEY"]

main.py contract

Kuttle runs main.py in its signed sandbox. Read one JSON object from standard input and write the useful result to standard output. The payload has three top-level objects:

{
  "input": {
    "text": "Count these words",
    "prompt": "Use word count for: Count these words",
    "activeApp": "Finder"
  },
  "tool": {
    "id": "word_count",
    "name": "Word Count"
  },
  "sandbox": {
    "backend": "macos-app-sandbox",
    "outputDirectory": "",
    "network": "denied",
    "subprocesses": "denied"
  }
}

The planner supplies fields declared by your schema. Kuttle also adds useful context such as prompt, activeApp, selectedPaths, finderPath, and browser metadata when available. Treat undeclared context as optional.

Example 1: current date

This zero-input tool uses only the Python standard library and returns JSON as a single stdout result.

import json
import sys
from datetime import datetime


def main():
    _payload = json.loads(sys.stdin.read() or "{}")
    now = datetime.now().astimezone()
    print(json.dumps({
        "result": now.strftime("%Y-%m-%d %H:%M:%S %Z"),
        "iso": now.isoformat()
    }))


if __name__ == "__main__":
    main()

Suggested request: @kuttle run the current_date tool.

Example 2: word count with input

This example reads the text property declared in the earlier manifest, validates it, and returns a compact structured result.

import json
import sys


def main():
    payload = json.loads(sys.stdin.read() or "{}")
    tool_input = payload.get("input", {})
    text = tool_input.get("text", "")

    if not isinstance(text, str) or not text.strip():
        raise ValueError("text must be a non-empty string")

    result = {
        "words": len(text.split()),
        "characters": len(text),
        "text": text
    }
    print(json.dumps(result))


if __name__ == "__main__":
    main()

Suggested request: @kuttle use the word_count tool to count: One request. Your Mac gets to work.

Install and test

1. Put tools.json and main.py in the same folder.
2. Open Settings → Tools → Installed Tools and choose Install tool.
3. Select the unpacked tool folder. Kuttle validates paths, package size, links, manifest data, and the entry point before copying it.
4. Confirm the tool appears as installed and that Settings → Tools → Tool Execution reports Sandbox verified.
5. Ask for the tool by its ID or describe a task that closely matches its description. Kuttle validates the chosen ID again before execution.

Settings → Files

Files

File actions are constrained by both operation policy and folder scope. A valid plan still fails if its path is outside an allowed root.

Settings → Runtime

Runtime