Skip to main content
Craft Agents organizes your conversations like an email inbox, making it easy to manage multiple ongoing tasks and return to previous work.

​
Multi-Conversation Inbox

Think of Craft Agents as an email client for AI conversations. Each conversation is a separate thread that you can:
  • Start, pause, and resume at any time
  • Organize by status (Todo, In Progress, Needs Review, Done, etc.)
  • Search and filter to find past work
  • Archive or delete when no longer needed
Multi-conversation inbox showing sessions with different statuses

​
Session ID Format

Each conversation has a unique session ID in the format: 
YYMMDD-adjective-noun
Where YY is the 2-digit year (e.g., 25 for 2025, 26 for 2026). For example:
  • 260121-swift-falcon - Created January 21, 2026
  • 260115-gentle-river - Created January 15, 2026
  • 260108-bright-mountain - Created January 8, 2026
This format makes sessions easy to identify by date while remaining human-readable and memorable.

​
Conversation Storage

Conversations are stored as JSONL (JSON Lines) files on your local machine at ~/.craft-agent/workspaces/{id}/sessions/{session-id}/session.jsonl. The file format is:
  • Line 1: Session header with metadata
  • Lines 2+: Messages (one per line)
{"id":"260121-swift-falcon","workspaceRootPath":"~/.craft-agent/workspaces/ws-abc123","createdAt":1737451800000,"lastUsedAt":1737451900000,"sessionStatus":"todo","permissionMode":"ask"}
{"id":"msg_1","type":"human","content":"Find my project planning document","timestamp":1737451800000}
{"id":"msg_2","type":"assistant","content":"Found \"Project Planning Q4\"...","timestamp":1737451802000}
Session header fields:
FieldDescription
idSession ID (YYMMDD-adjective-noun)
workspaceRootPathPath to workspace (portable format)
createdAtCreation timestamp (ms)
lastUsedAtLast activity timestamp (ms)
sessionStatusStatus ID (e.g., “todo”, “done”)
permissionModeCurrent mode: “safe”, “ask”, “allow-all”
nameOptional user-defined name
isFlaggedWhether session is flagged
modelModel override for this session
llmConnectionLLM connection slug (locked after first message)
connectionLockedWhether the connection is locked (cannot change after first message)
thinkingLevelThinking level: "off", "think", or "max"
workingDirectoryWorking directory for bash commands
enabledSourceSlugsArray of active source slugs
This format provides:
  • Fast list loading - Only the first line is read for inbox display
  • Efficient streaming - Messages can be appended without rewriting the file
  • Easy parsing - Each line is independent and can be processed separately

​
Status-Based Organization

Conversations can be organized by status to track your workflow:
StatusCategoryDescription
TodoOpenConversations waiting to be addressed
In ProgressOpenConversations you’re actively working on
Needs ReviewOpenRequires review before completion
DoneClosedCompleted conversations
CancelledClosedConversations that are no longer needed
Open statuses appear in your inbox; Closed statuses are archived. You can customize statuses to match your workflow—add custom statuses like “Blocked” or “Waiting” to fit your process.

​
Batch Operations

Select multiple sessions to perform bulk actions. Hold ⌘ Click (macOS) or Ctrl+Click (Windows/Linux) to toggle individual sessions, or ⇧ Click for range selection. When multiple sessions are selected, a batch action panel appears with these operations:
ActionDescription
Change StatusSet the same status on all selected sessions
Set LabelsToggle labels across all selected sessions
Flag / UnflagFlag or unflag all selected sessions
ArchiveArchive all selected sessions
DeletePermanently delete all selected sessions
Press Esc to clear the selection.
Right-click on a multi-selection to access these same actions via a context menu, which also includes flag/unflag and delete options.

​
Conversation Continuity

When you return to a conversation, Craft Agents restores the full context:
  • All previous messages are available
  • The agent remembers what you discussed
  • You can continue exactly where you left off
  • Referenced documents and files are still accessible
> Resuming session 250121-swift-falcon...

Last message: "I've identified the auth module dependencies"

> Great, let's start refactoring
Continuing from where we left off. I'll begin with the AuthProvider component...

​
How Conversations Work

Each conversation is tied to a workspace. When you chat with Craft Agents:
  • The agent remembers what you discussed earlier in the session
  • You can reference previous topics (“summarize that document”, “add another task like before”)
  • Context builds up naturally as you work
> Find my project planning document
Found "Project Planning Q4" - here's an overview...

> Add a new section called "Timeline"
Added "Timeline" section to Project Planning Q4.

> Now add three tasks to that section
Added 3 tasks to the Timeline section:
1. Define milestones
2. Set deadlines
3. Assign owners

​
Starting New Conversations

To start a fresh conversation, click the New Chat button in the sidebar or use the keyboard shortcut. This creates a new chat with a fresh ID while preserving your previous conversations in the inbox.

​
Using Skills in Conversations

Skills are specialized capabilities you can invoke using bracket syntax. When you mention a skill, it activates with full access to your conversation history: 
> Find my project planning document
Found "Project Planning Q4" - here's an overview...

> [skill:research] Find background research on our Q4 goals
Activating research skill...
[The skill can reference the project planning document from the previous exchange]
This means:
  • Skills can reference documents and context from earlier in the conversation
  • The full conversation history is preserved when using skills
  • You can chain skills together, each building on previous work
Learn more about creating and using skills in the Skills documentation.

​
Long Conversations

For extended work sessions, Craft Agents automatically manages context:
  • Large tool results (over 15,000 tokens) are automatically summarized to save context space
  • The Claude Agent SDK handles context window management transparently
  • Recent context is always available for reference
You don’t need to manage this manually - the system handles it transparently.

​
Conversation Across Workspaces

Each workspace has independent conversation history:
WorkspaceConversation
Personal NotesSeparate history
Work ProjectsSeparate history
Shared Team SpaceSeparate history
Switching workspaces switches to that workspace’s conversation context.

​
Tips for Effective Conversations

Say “that document” or “the task we just created” instead of repeating full names. The agent tracks what you’re discussing.
After creating something, you can immediately modify it: “now add a due date” or “change the title”.
If the agent misunderstands, just clarify: “no, I meant the other project” or “the one from last week”.
Mark conversations as Todo, Needs Review, or Done to keep track of your work across multiple threads.