Craft Agents - The way working with AI Agents should feel

TL;DR

Craft Agents separates riskier actions into explore mode (plan only) and execute mode (command execution), with an additional “ask to edit” permission gate for specific filesystem changes.

Briefing Cornell Notes

Briefing

Craft Agents is an open-source, multiplatform AI “agent” app built to make day-to-day work with AI feel controlled, auditable, and fast—especially when the agent needs to touch a user’s files or connect to external tools. The core pitch is an agent workflow that separates planning from execution, shows exactly what commands and configuration changes it intends to make, and then asks for permission when real-world actions are at stake.

After installing from agents.craft.2 (Mac with Apple silicon, Mac with Intel, Windows, and Linux) users choose how to connect to an AI endpoint. Craft Agents supports cloud subscriptions by default (recommended for best experience) and also offers alternatives such as direct API key connections, OpenRouter, Vercel AI gateway, Ollama, or other custom providers. Once connected, new chats can start immediately, but the app’s standout behavior appears when tasks require system access. In a demo, the agent is asked to reorganize the user’s downloads folder, identify deletable items, and estimate storage savings. Instead of blindly running commands, it uses an “explore mode” that blocks execution and produces a plan. The UI then reveals the steps it would take—down to the commands and outputs—along with why certain actions were blocked (for example, because execution is restricted in explore mode).

Users can then accept the plan to switch into “execute mode,” where the agent carries out file operations (deleting, moving, creating folders) and provides a running to-do list. If trust is an issue, Craft Agents supports an “ask to edit” style: the agent proposes a specific filesystem change, lists the exact files involved, and prompts for permission (including options like always allow or deny). For users who want fewer interruptions, switching back to execute mode allows the agent to continue without repeated confirmations.

Beyond local actions, Craft Agents emphasizes “sources” as the mechanism for connecting tools. A dedicated sources menu supports APIs, MCPs, and even local folders. Rather than requiring users to understand every integration, the app can guide setup through documentation and guided prompts. In examples, it walks through connecting to Linear (issues/tickets) and GitHub (listing issues and organizing pull requests), handling authentication via secure credential storage and prompting for API keys only when needed. The app also provides an edit view showing configuration diffs—lines added or removed—so users can audit what changed.

Organization is handled through statuses, labels, and auto-apply rules. Conversations start in a default status but can be moved with one click or hashtag shortcuts. Labels can be assigned automatically using rules (e.g., any session containing “bill” or “invoice” gets an “invoices” label). Search is designed for scale, with fast retrieval across thousands of sessions and the ability to highlight matches inside both the session list and the conversation body, plus AI-generated title regeneration.

Finally, Craft Agents turns multi-step workflows into reusable “skills.” A weekend-planning skill for Lake Balaton demonstrates combining sources (Outlook calendar, weather lookup, and cat-facts API) into a single plan that can be triggered later. Skills can be visualized as Mermaid flowcharts, showing decision branches (season-based activity suggestions) and the sequence of actions (web search, weather-based recommendations, calendar event creation, and final presentation). The overall message: agentic automation is most usable when it’s planned, permissioned, connected to real tools, and easy to audit.

Cornell Notes

Craft Agents is an open-source, multiplatform AI agent app designed for practical work: it plans before it acts, shows what it will do, and then executes with user permission when tasks affect files or external systems. Users connect to AI endpoints (cloud subscriptions recommended, but API keys, OpenRouter, Vercel AI gateway, Ollama, and custom options are supported), then run chats that can switch between explore mode (plan only) and execute mode (run commands). The app also manages “sources” like APIs and MCPs, guiding setup for tools such as Linear and GitHub while storing credentials securely and displaying configuration diffs. Organization features—statuses, labels, auto-apply rules, and fast search—help users manage thousands of conversations. Reusable “skills” bundle multi-step workflows and can be rendered as Mermaid flowcharts for clarity.

How does Craft Agents prevent an AI from taking risky actions immediately?

It uses a planning-first workflow with modes. In “explore mode,” the agent cannot execute commands; instead it creates a plan and explains why execution is blocked. The UI shows the steps it would run (including commands and outputs) and the reason for restrictions (e.g., blocked because it’s in explore mode). After the user reviews the plan, “accept” switches to “execute mode,” where file operations and other actions proceed. For extra control, “ask to edit” pauses execution and prompts for permission per change, listing the exact files and the command it intends to run.

What does “accept and compact” do, and why does it matter for long tasks?

When a user chooses “accept and compact,” Craft Agents keeps the conversation context but compresses it by summarizing what has already been discussed. It then reinjects the plan so the agent still knows what it needs to do when switching into execution. This helps maintain continuity while reducing context bloat during multi-step workflows.

How are external tools integrated, and what makes setup less painful?

Integration happens through “sources,” which can be APIs, MCPs, or local folders. Users can either configure connections directly or use a guided “learn more” flow where the agent consults documentation and even performs web search to find how to connect to an official MCP server. In the Linear example, the agent asks questions about intended usage (teams/projects, access level), generates configuration files, and then prompts the user to log in via a browser approval step. For GitHub, it requests an API key through a secure UI card and then enables the connection for follow-up tasks like listing issues.

What audit and security features show up when the agent changes configuration or touches credentials?

Craft Agents provides an edit view for configuration changes, including how many lines were added or removed, plus highlighting to make diffs readable. Credentials are handled via authentication cards and stored in secure local credential storage rather than being kept in chat sessions. When authentication is required, the app prompts the user in a secure way (e.g., API key entry or browser sign-in approval) before continuing.

How do statuses, labels, and auto-apply rules organize conversations?

Conversations live under statuses such as to-dos, ideas, in progress, needs preview, and even custom ones. Users can move a conversation with one click or by using hashtag shortcuts (e.g., jumping back to “in progress”). Labels add topic-based organization (like an “invoices” label). Auto-apply rules can automatically assign labels based on conversation content; for example, sessions containing “bill” or “invoice” can be routed into the invoices label without manual tagging.

What are skills, and how do they help with repeatable workflows?

Skills package multi-step agent workflows into reusable triggers. A demo skill (“Bolaton weekend planner”) combines steps like checking weather forecasts, recommending activities based on season, adding cat facts, and creating an all-day calendar blocker in Outlook. Skills can be modified and reused later, and Craft Agents can generate Mermaid flowcharts that visualize the workflow, including decision branches (winter/autumn/spring/summer) and the sequence of actions.

Review Questions

When would a user choose explore mode versus execute mode, and what UI evidence confirms the agent’s plan before execution?
How does Craft Agents handle authentication for sources like Linear and GitHub, and what mechanisms prevent credentials from being stored in chat sessions?
Describe how statuses, labels, and auto-apply rules work together to keep large conversation histories navigable.

Key Points

1
Craft Agents separates riskier actions into explore mode (plan only) and execute mode (command execution), with an additional “ask to edit” permission gate for specific filesystem changes.
2
The UI provides step-by-step transparency, including the exact commands the agent intends to run and the reasons execution is blocked in explore mode.
3
Sources unify integrations across APIs, MCPs, and local folders, with guided setup that can use documentation and web search to reduce manual configuration.
4
Configuration changes are auditable via diff-style edit views (lines added/removed), while credentials are handled through secure authentication cards and local credential storage.
5
Statuses and labels organize conversations, and auto-apply rules can automatically tag sessions based on content keywords.
6
Search is optimized for speed across thousands of sessions, highlighting matches both in the session list and inside conversation bodies, with AI-assisted title regeneration.
7
Skills turn multi-source workflows into reusable routines and can be visualized as Mermaid flowcharts for easier understanding and auditing.

Highlights

The agent’s “explore mode” blocks command execution and produces a plan first, then “execute mode” runs the approved steps—making file operations auditable.

Craft Agents can connect to tools like Linear and GitHub by generating configuration files, requesting authentication securely, and showing configuration diffs line-by-line.

Auto-apply rules can automatically assign labels to conversations based on content (e.g., “bill”/“invoice” → invoices label).

Skills can be rendered into Mermaid flowcharts, showing season-based decision branches and the exact sequence of actions (weather → activities → cat facts → calendar event).

Topics

AI Agents
Planning vs Execution
Filesystem Permissions
Tool Integrations
Skills and Workflows

Mentioned

MCP
UI
JSON
API
OS