Skip to main content

​
Overview

This guide walks you through:
  1. Launching Craft Agents
  2. Connecting an AI provider
  3. Creating your first workspace
  4. Starting your first agent session
Before starting, make sure you have installed Craft Agents.

​
Step 1: Launch the App

Open Craft Agents from your Applications folder, Start menu, or app launcher. On first launch, you’ll see the welcome screen.

​
Step 2: Choose an AI Provider

Craft Agents supports multiple AI providers. Choose the one that works best for you:

Anthropic

API Key or Claude Max/Pro subscriptionMost popular option. Direct access to Claude via the Agent SDK.

Google AI Studio

API Key from Google AI StudioAccess Gemini models with built-in Google Search grounding.

ChatGPT Plus

OAuth with ChatGPT subscriptionOne-click sign-in with your ChatGPT Plus or Pro account.

GitHub Copilot

OAuth with Copilot subscriptionDevice code authentication with your GitHub Copilot subscription.

​
Connecting with Anthropic

1

Get an API Key

Go to Anthropic Console and create a new API key.
If you have a Claude Max or Pro subscription, you can use OAuth instead - just click “Sign in with Claude” in the app.
2

Add Connection in Craft Agents

  1. Click “Add LLM Connection” in the app
  2. Choose “Anthropic (Claude Agent SDK)”
  3. Paste your API key
  4. Give it a name (e.g., “Claude API”)
  5. Click Save

​
Connecting with Google AI Studio

1

Get an API Key

  1. Go to Google AI Studio
  2. Click “Create API Key”
  3. Copy the key
2

Add Connection in Craft Agents

  1. Click “Add LLM Connection”
  2. Choose “Google AI Studio”
  3. Paste your API key
  4. Choose your preferred model (e.g., gemini-2.0-flash-exp)
  5. Click Save

​
Alternative: OpenRouter, Ollama, Custom APIs

Craft Agents also supports third-party and self-hosted providers:
  • OpenRouter: Access hundreds of models through one API key
  • Ollama: Run models locally at http://localhost:11434
  • Custom endpoints: Any OpenAI or Anthropic-compatible API
For OpenRouter, choose “Anthropic (Claude Agent SDK)” connection type, then set the endpoint to https://openrouter.ai/api.

​
Step 3: Create a Workspace

Workspaces help you organize sessions by project, team, or context.
1

Click 'New Workspace'

In the sidebar, click the ”+” button or “New Workspace” link.
2

Configure Workspace

  • Name: Give it a clear name (e.g., “Personal Projects”, “Work - iOS Team”)
  • Default LLM: Choose the AI provider you just connected
  • Permission Mode: Start with “Ask to Edit” (you can change this per-session)
3

Save

Click Create to save your workspace.
Your workspace is now active and ready for sessions.

​
Step 4: Start Your First Session

Now let’s create your first agent conversation:
1

Create a New Session

Press Cmd+N (macOS) or Ctrl+N (Windows/Linux), or click “New Chat”.
2

Send Your First Message

Try something simple to test the connection:
Hello! Can you help me understand what Craft Agents can do?
Press Enter to send.
3

Watch the Agent Respond

You’ll see:
  • Streaming text response
  • Tool use visualization (if the agent uses tools)
  • Real-time status updates
Your first message might take a few seconds as the agent initializes. Subsequent messages will be faster.

​
Understanding Permission Modes

Notice the permission indicator in the chat interface. Craft Agents has three modes:
ModeDisplayBehavior
Explore🔍 ExploreRead-only - blocks all write operations
Ask to Edit✋ Ask to EditPrompts before making changes (default)
Auto⚡ AutoAuto-approves all commands
Toggle modes instantly with SHIFT+TAB.
Start with Ask to Edit mode. Switch to Explore when browsing unfamiliar code, or Auto when you trust the agent completely.

​
Try Something Useful

Now that you’re set up, try asking the agent to help with a real task: 
Can you analyze the structure of my project at ~/code/my-app?
Show me the main components and how they're organized.

​
Next Steps

​
Add Sources

Sources let you connect external data and services. Try: 
Add GitHub as a source
The agent will:
  1. Find the GitHub MCP server
  2. Set up authentication
  3. Configure it for your workspace
You can then use @github in messages to interact with your repositories.

Learn about Sources

Connect MCP servers, REST APIs, and local filesystems

​
Create Skills

Skills are specialized instructions for recurring tasks: 
Create a skill called "code-review" that checks for:
- Code quality and style
- Security issues
- Performance considerations
Skills are compatible with Claude Code SDK format and can be invoked with slash commands like /code-review.

Learn about Skills

Create custom agent instructions for your workflows

​
Set Up Automations

Automate workflows with event-driven triggers: 
Set up a daily standup briefing every weekday at 9am
that summarizes my GitHub issues and Linear tickets

Learn about Automations

Trigger agent sessions on schedules, labels, and events

​
Keyboard Shortcuts

Speed up your workflow with these shortcuts:
ShortcutAction
Cmd+N / Ctrl+NNew chat
Cmd+1/2/3Focus sidebar / session list / chat
Cmd+/Show keyboard shortcuts
SHIFT+TABCycle permission modes
EnterSend message
Shift+EnterNew line in message
Press Cmd+/ (or Ctrl+/) anytime to see all available shortcuts.

​
Common First Tasks

​
Connecting Your Obsidian Vault

Add a local filesystem source for my Obsidian vault at ~/Documents/ObsidianVault
The agent creates a local source and you can now search and read your notes with @obsidian.

​
Importing Claude Code Skills

If you’re coming from Claude Code: 
Import all my skills from Claude Code
The agent migrates your skills automatically.

​
Setting Up Your Team’s GitHub Org

Connect to GitHub and focus on the "mycompany" organization.
I mainly work on the "web-app" and "mobile-app" repositories.
The agent configures GitHub access and documents your focus areas in the source guide.

​
Tips for Success

Be Specific

“Create a Next.js API route for user authentication” works better than “help me with Next.js”

Use @mentions

Reference sources and skills: “Using @github, show me recent PRs”

Iterate in Sessions

Keep conversations in one session. The agent remembers context.

Organize with Statuses

Use Todo → In Progress → Done workflow to track session progress

​
Getting Help

If you run into issues:
  1. Check the docs: This documentation covers all features in detail
  2. Enable debug mode: Launch with -- --debug flag to see detailed logs
  3. Ask the agent: “How do I connect to Linear?” - the agent can help with setup
  4. GitHub Issues: Report bugs or request features
Craft Agents stores all configuration at ~/.craft-agent/. If you need to reset everything, quit the app and delete this folder. Your conversations and credentials will be removed.

​
What’s Next?

You’re now ready to use Craft Agents! Explore the documentation to learn about:

Sources

Connect to MCP servers, APIs, and local files

Skills

Create specialized agent instructions

Permissions

Control what agents can do in each mode

Automations

Set up event-driven workflows

Build docs developers (and LLMs) love

Get started for freeTalk to us