FAQ

​

General

​

What are Craft Agents?

Craft Agents is a terminal-based AI assistant that connects to your Craft documents. It uses Claude (by Anthropic) to help you manage, search, and interact with your Craft workspace through natural language. You can also build custom agents and agentic workflows as simple as creating documents in your Craft Space. Define instructions, connect MCP servers, and integrate REST APIs - all from within Craft.

​

What models are available?

Craft Agents supports several Claude models: Use /model to switch models during a conversation.

​

How do I switch between billing methods?

Use /settings to change your billing method:

• Craft Credits - Use your Craft subscription
• Anthropic API Key - Pay-as-you-go directly with Anthropic
• Claude Max - Use your Claude Pro/Max subscription

After switching, you need to restart the app for changes to take effect.

​

Troubleshooting

​

I’m getting API errors (400, 500)

Try these steps in order:

1. Clear your conversation - Run /clear to reset the session. This fixes most issues caused by corrupted session data.
2. Check your credentials - Run /settings to verify your billing method and credentials are configured correctly.
3. Restart the app - Exit with Ctrl+C and reopen.

​

My conversation seems corrupted

Run /clear to reset your conversation and session. This clears:

• All messages in the current conversation
• The SDK session state
• Saved conversation data

Your credentials and workspace settings are preserved.

​

The app says “MCP authentication required”

Your workspace needs to re-authenticate with the MCP server. This can happen if:

• Your OAuth token expired
• You removed and re-added the workspace
• The MCP server configuration changed

To fix this:

1. Run /workspace to open the workspace menu
2. Press d to remove the affected workspace
3. Re-add the workspace with fresh authentication

As a last resort, use /logout to reset everything and start the setup from scratch.

​

Workspaces

​

What is a workspace?

A workspace connects Craft Agent to a specific Craft space via an MCP server. Each workspace has:

• Its own MCP server URL
• Separate authentication credentials
• Independent conversation history

​

How do I switch workspaces?

Use /workspace to see available workspaces and switch between them. Or use /workspace <name> to switch directly.

​

How do I add a new workspace?

Use /workspace add to start the workspace creation wizard. You’ll need:

• A name for the workspace
• The MCP server URL for your Craft space

​

Sub-Agents

​

What are sub-agents?

Sub-agents are specialized AI assistants you create in Craft documents. They have custom instructions, can connect to additional MCP servers, and integrate with REST APIs.

​

How do I activate a sub-agent?

Type @agentname in your message to activate an agent. Use Tab for auto-completion of available agent names.

​

How do I create a sub-agent?

Create a document in your “Agents” folder in Craft. Add an “Instructions” section with your agent’s behavior. See the Sub-Agents documentation for details.

​

How do I reload an agent’s instructions?

Use /agent reload to fetch the latest instructions from the Craft document without losing your conversation. If reload doesn’t work, use /agent reset to force a full reload. Note that reset clears your conversation history with that agent and starts fresh from the beginning.

​

Plan Mode

​

What is Plan Mode?

Plan Mode is a structured workflow for complex tasks. Instead of executing actions immediately, the agent first creates a plan, gets your approval, then executes. This gives you visibility and control over multi-step operations.

​

How do I enter Plan Mode?

There are several ways to enter Plan Mode:

​

How do I exit Plan Mode?

• After planning: Use /plan approve to execute, or /plan cancel to exit without executing
• Quick exit: Press Shift+Tab again to toggle off
• Via menu: Type /plan and select “Cancel Plan Mode”

​

Can I save plans for later?

Yes. Plans are automatically saved and can be accessed with /plan plans. From there you can load a previous plan or delete ones you no longer need.

​

How do I access plans from other sessions?

Plans are stored per session. To access plans from a different session:

1. Use /resume to open the session menu
2. Select the session that contains your plans (the menu shows how many plans each session has)
3. Press Enter to resume that session
4. Your plans are now accessible via /plan plans

​

Commands

​

What commands are available?

​

How do I see my token usage?

Use /context to see how much of the conversation memory is being used. This shows your current token usage and available context window capacity. Token usage is also shown in the status bar at the top. Use /settings to configure how tokens are displayed (hidden, total, or separate input/output).

​

Privacy & Security

​

Where is my data stored?

• Configuration: ~/.craft-agent/config.json
• Credentials: ~/.craft-agent/credentials.enc (AES-256-GCM encrypted)
• Conversations: ~/.craft-agent/workspaces/<id>/conversation.json

​

Are my credentials secure?

Yes. All sensitive credentials (API keys, OAuth tokens) are stored in an encrypted file using AES-256-GCM encryption with a machine-derived key. No credentials are stored in plain text.

​

Does Craft Agent send data to third parties?

Craft Agent sends your messages to:

• Anthropic (Claude API) - for AI responses
• Your Craft MCP server - for document operations

No data is sent elsewhere unless you explicitly configure additional MCP servers or REST APIs in your sub-agents.