Skip to main content

​
Monorepo Structure

Craft Agents is organized as a Bun-powered monorepo using workspace packages. The codebase is split into two main directories: 
craft-agent/
├── apps/
│   ├── electron/              # Desktop GUI (primary app)
│   └── viewer/                # Session sharing viewer
└── packages/
    ├── core/                  # Shared TypeScript types
    ├── shared/                # Business logic & utilities
    ├── pi-agent-server/       # Pi SDK subprocess
    ├── session-mcp-server/    # Session MCP server
    ├── session-tools-core/    # Session tool definitions
    └── ui/                    # Shared UI components
The monorepo uses workspace packages (workspace:*) to share code between apps and packages without publishing to npm.

​
Apps vs Packages

​
Apps Directory

Contains user-facing applications:
  • electron/ - Primary desktop application built with Electron, React, and Vite
  • viewer/ - Web-based session sharing viewer for public session links

​
Packages Directory

Contains reusable libraries and internal services:
PackagePurpose
@craft-agent/coreShared TypeScript types and interfaces
@craft-agent/sharedBusiness logic (agent, auth, config, MCP)
@craft-agent/uiShared React components with shadcn/ui
@craft-agent/pi-agent-serverOut-of-process Pi agent server
@craft-agent/session-mcp-serverMCP server for session introspection
@craft-agent/session-tools-coreCore session tool definitions

Learn More

Deep dive into the packages architecture and exports

​
Tech Stack

Craft Agents is built with modern, high-performance technologies:

​
Runtime & Build

TechnologyUsage
BunJavaScript runtime and package manager
esbuildMain process bundler (fast, native)
ViteRenderer process dev server and bundler

​
Desktop & UI

TechnologyUsage
ElectronDesktop app framework (native APIs)
React 18UI framework with Hooks
shadcn/uiRadix UI + Tailwind CSS components
Tailwind CSS v4Utility-first styling
JotaiAtomic state management
MotionAnimation library

​
AI & Agent SDKs

Claude Agent SDK

Powers Anthropic, OpenRouter, and custom endpoints

Pi SDK

Powers Google AI Studio, ChatGPT Plus, and GitHub Copilot
TechnologyUsage
@anthropic-ai/claude-agent-sdkClaude-based agent backend
@mariozechner/pi-coding-agentPi-based agent backend
@modelcontextprotocol/sdkMCP server integration

Agent Backends

Learn how Craft Agents routes between Claude and Pi backends

​
Key Technologies

​
Electron Architecture

Craft Agents uses Electron’s multi-process architecture:
  • Main Process - Node.js backend with full system access
  • Renderer Process - Chromium frontend (isolated, sandboxed)
  • Preload Scripts - Context bridge between main and renderer

Electron Deep Dive

Explore IPC channels, window management, and build process

​
Configuration Storage

All user data lives in ~/.craft-agent/: 
~/.craft-agent/
├── config.json              # Workspaces, LLM connections
├── credentials.enc          # AES-256-GCM encrypted secrets
├── preferences.json         # User preferences
├── theme.json               # App-level theme
└── workspaces/
    └── {id}/
        ├── config.json      # Workspace settings
        ├── theme.json       # Workspace theme override
        ├── sessions/        # Session data (JSONL)
        ├── sources/         # MCP servers & API configs
        ├── skills/          # Custom agent skills
        └── automations.json # Event-driven automations
File-based storage keeps the architecture simple and agent-editable. The agent can directly read and modify its own configuration using filesystem tools, making it truly “agent-native software.”

​
Credentials Security

All sensitive credentials (API keys, OAuth tokens) are stored in an AES-256-GCM encrypted file at ~/.craft-agent/credentials.enc. The encryption key is derived from system-specific entropy.

​
Session Persistence

Sessions are stored as JSONL files (JSON Lines format):
  • One line per message
  • Streaming-friendly (append-only)
  • Easy to debug and inspect
  • Portable across systems

​
Development Workflow

bun run electron:dev

​
Debug Logging

Logs are automatically written in development:
  • macOS: ~/Library/Logs/@craft-agent/electron/main.log
  • Windows: %APPDATA%\@craft-agent\electron\logs\main.log
  • Linux: ~/.config/@craft-agent/electron/logs/main.log
Launch with -- --debug flag to enable verbose logging in production builds.

​
Next Steps

Electron App

Main/preload/renderer processes and IPC

Packages

Core and shared package exports

Agent Backends

Claude vs Pi SDK routing

Build docs developers (and LLMs) love

Get started for freeTalk to us