Initial commit: 1Code v0.0.10

Open source release of 1Code - Best UI for Claude Code with Local and Remote agent execution.

Apache License 2.0

Author: serafimcloud

.env.example

@@ -0,0 +1,17 @@
+# Apple Developer credentials (required for macOS code signing & notarization)
+APPLE_ID=your-email@example.com
+APPLE_APP_SPECIFIC_PASSWORD=xxxx-xxxx-xxxx-xxxx
+APPLE_TEAM_ID=XXXXXXXXXX
+APPLE_IDENTITY=Developer ID Application: Your Name (TEAM_ID)
+
+# Sentry error tracking (optional - disabled if not set)
+# Main process uses MAIN_VITE_ prefix
+MAIN_VITE_SENTRY_DSN=https://xxxxx@xxx.ingest.sentry.io/xxxxx
+
+# PostHog analytics (optional - disabled if not set)
+# Main process (MAIN_VITE_ prefix for electron-vite)
+MAIN_VITE_POSTHOG_KEY=phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+MAIN_VITE_POSTHOG_HOST=https://us.i.posthog.com
+# Renderer process (VITE_ prefix for Vite)
+VITE_POSTHOG_KEY=phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+VITE_POSTHOG_HOST=https://us.i.posthog.com

.gitignore

@@ -0,0 +1,32 @@
+# Dependencies
+node_modules/
+
+# Build outputs
+dist/
+release/
+release-*/
+out/
+
+# IDE
+.idea/
+*.swp
+*.swo
+.vscode/
+
+# System files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+
+# Environment
+.env
+.env.local
+
+# electron-vite temp files
+electron.vite.config.*.mjs
+
+# Claude binary (downloaded at build time)
+resources/bin/

CLAUDE.md

@@ -0,0 +1,230 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What is this?
+
+**21st Agents** - A local-first Electron desktop app for AI-powered code assistance. Users create chat sessions linked to local project folders, interact with Claude in Plan or Agent mode, and see real-time tool execution (bash, file edits, web search, etc.).
+
+## Commands
+
+```bash
+# Development
+bun run dev              # Start Electron with hot reload
+
+# Build
+bun run build            # Compile app
+bun run package          # Package for current platform (dir)
+bun run package:mac      # Build macOS (DMG + ZIP)
+bun run package:win      # Build Windows (NSIS + portable)
+bun run package:linux    # Build Linux (AppImage + DEB)
+
+# Database (Drizzle + SQLite)
+bun run db:generate      # Generate migrations from schema
+bun run db:push          # Push schema directly (dev only)
+```
+
+## Architecture
+
+```
+src/
+├── main/                    # Electron main process
+│   ├── index.ts             # App entry, window lifecycle
+│   ├── auth-manager.ts      # OAuth flow, token refresh
+│   ├── auth-store.ts        # Encrypted credential storage (safeStorage)
+│   ├── windows/main.ts      # Window creation, IPC handlers
+│   └── lib/
+│       ├── db/              # Drizzle + SQLite
+│       │   ├── index.ts     # DB init, auto-migrate on startup
+│       │   ├── schema/      # Drizzle table definitions
+│       │   └── utils.ts     # ID generation
+│       └── trpc/routers/    # tRPC routers (projects, chats, claude)
+│
+├── preload/                 # IPC bridge (context isolation)
+│   └── index.ts             # Exposes desktopApi + tRPC bridge
+│
+└── renderer/                # React 19 UI
+    ├── App.tsx              # Root with providers
+    ├── features/
+    │   ├── agents/          # Main chat interface
+    │   │   ├── main/        # active-chat.tsx, new-chat-form.tsx
+    │   │   ├── ui/          # Tool renderers, preview, diff view
+    │   │   ├── commands/    # Slash commands (/plan, /agent, /clear)
+    │   │   ├── atoms/       # Jotai atoms for agent state
+    │   │   └── stores/      # Zustand store for sub-chats
+    │   ├── sidebar/         # Chat list, archive, navigation
+    │   ├── sub-chats/       # Tab/sidebar sub-chat management
+    │   └── layout/          # Main layout with resizable panels
+    ├── components/ui/       # Radix UI wrappers (button, dialog, etc.)
+    └── lib/
+        ├── atoms/           # Global Jotai atoms
+        ├── stores/          # Global Zustand stores
+        ├── trpc.ts          # Real tRPC client
+        └── mock-api.ts      # DEPRECATED - being replaced with real tRPC
+```
+
+## Database (Drizzle ORM)
+
+**Location:** `{userData}/data/agents.db` (SQLite)
+
+**Schema:** `src/main/lib/db/schema/index.ts`
+
+```typescript
+// Three main tables:
+projects    → id, name, path (local folder), timestamps
+chats       → id, name, projectId, worktree fields, timestamps
+sub_chats   → id, name, chatId, sessionId, mode, messages (JSON)
+```
+
+**Auto-migration:** On app start, `initDatabase()` runs migrations from `drizzle/` folder (dev) or `resources/migrations` (packaged).
+
+**Queries:**
+```typescript
+import { getDatabase, projects, chats } from "../lib/db"
+import { eq } from "drizzle-orm"
+
+const db = getDatabase()
+const allProjects = db.select().from(projects).all()
+const projectChats = db.select().from(chats).where(eq(chats.projectId, id)).all()
+```
+
+## Key Patterns
+
+### IPC Communication
+- Uses **tRPC** with `trpc-electron` for type-safe main↔renderer communication
+- All backend calls go through tRPC routers, not raw IPC
+- Preload exposes `window.desktopApi` for native features (window controls, clipboard, notifications)
+
+### State Management
+- **Jotai**: UI state (selected chat, sidebar open, preview settings)
+- **Zustand**: Sub-chat tabs and pinned state (persisted to localStorage)
+- **React Query**: Server state via tRPC (auto-caching, refetch)
+
+### Claude Integration
+- Dynamic import of `@anthropic-ai/claude-code` SDK
+- Two modes: "plan" (read-only) and "agent" (full permissions)
+- Session resume via `sessionId` stored in SubChat
+- Message streaming via tRPC subscription (`claude.onMessage`)
+
+## Tech Stack
+
+| Layer | Tech |
+|-------|------|
+| Desktop | Electron 33.4.5, electron-vite, electron-builder |
+| UI | React 19, TypeScript 5.4.5, Tailwind CSS |
+| Components | Radix UI, Lucide icons, Motion, Sonner |
+| State | Jotai, Zustand, React Query |
+| Backend | tRPC, Drizzle ORM, better-sqlite3 |
+| AI | @anthropic-ai/claude-code |
+| Package Manager | bun |
+
+## File Naming
+
+- Components: PascalCase (`ActiveChat.tsx`, `AgentsSidebar.tsx`)
+- Utilities/hooks: camelCase (`useFileUpload.ts`, `formatters.ts`)
+- Stores: kebab-case (`sub-chat-store.ts`, `agent-chat-store.ts`)
+- Atoms: camelCase with `Atom` suffix (`selectedAgentChatIdAtom`)
+
+## Important Files
+
+- `electron.vite.config.ts` - Build config (main/preload/renderer entries)
+- `src/main/lib/db/schema/index.ts` - Drizzle schema (source of truth)
+- `src/main/lib/db/index.ts` - DB initialization + auto-migrate
+- `src/renderer/features/agents/atoms/index.ts` - Agent UI state atoms
+- `src/renderer/features/agents/main/active-chat.tsx` - Main chat component
+- `src/main/lib/trpc/routers/claude.ts` - Claude SDK integration
+
+## Debugging First Install Issues
+
+When testing auth flows or behavior for new users, you need to simulate a fresh install:
+
+```bash
+# 1. Clear all app data (auth, database, settings)
+rm -rf ~/Library/Application\ Support/Agents\ Dev/
+
+# 2. Reset macOS protocol handler registration (if testing deep links)
+/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -kill -r -domain local -domain system -domain user
+
+# 3. Clear app preferences
+defaults delete dev.21st.agents.dev  # Dev mode
+defaults delete dev.21st.agents      # Production
+
+# 4. Run in dev mode with clean state
+cd apps/desktop
+bun run dev
+```
+
+**Common First-Install Bugs:**
+- **OAuth deep link not working**: macOS Launch Services may not immediately recognize protocol handlers on first app launch. User may need to click "Sign in" again after the first attempt.
+- **Folder dialog not appearing**: Window focus timing issues on first launch. Fixed by ensuring window focus before showing `dialog.showOpenDialog()`.
+
+**Dev vs Production App:**
+- Dev mode uses `twentyfirst-agents-dev://` protocol
+- Dev mode uses separate userData path (`~/Library/Application Support/Agents Dev/`)
+- This prevents conflicts between dev and production installs
+
+## Releasing a New Version
+
+### Prerequisites for Notarization
+
+Set environment variables (add to `.zshrc` or `.env.local`):
+
+```bash
+export APPLE_ID="your-apple-id@example.com"
+export APPLE_APP_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"  # App-specific password from appleid.apple.com
+```
+
+### Release Commands
+
+```bash
+# Full release (build, sign, notarize, generate manifests, upload to CDN)
+bun run release
+
+# Or step by step:
+bun run build              # Compile TypeScript
+bun run package:mac        # Build, sign & notarize macOS app
+bun run dist:manifest      # Generate latest-mac.yml manifests
+./scripts/upload-release-wrangler.sh  # Upload to R2 CDN
+```
+
+### Bump Version Before Release
+
+```bash
+npm version patch  # 0.0.2 → 0.0.3
+npm version minor  # 0.0.3 → 0.1.0
+npm version major  # 0.1.0 → 1.0.0
+```
+
+### Files Uploaded to CDN
+
+| File | Purpose |
+|------|---------|
+| `latest-mac.yml` | Manifest for arm64 auto-updates |
+| `latest-mac-x64.yml` | Manifest for Intel auto-updates |
+| `Agents-{version}-arm64-mac.zip` | Auto-update payload (arm64) |
+| `Agents-{version}-mac.zip` | Auto-update payload (Intel) |
+| `Agents-{version}-arm64.dmg` | Manual download (arm64) |
+| `Agents-{version}.dmg` | Manual download (Intel) |
+
+### Auto-Update Flow
+
+1. App checks `https://cdn.21st.dev/releases/desktop/latest-mac.yml` on startup and when window regains focus (with 1 min cooldown)
+2. If version in manifest > current version, shows "Update Available" banner
+3. User clicks Download → downloads ZIP in background
+4. User clicks "Restart Now" → installs update and restarts
+
+## Current Status (WIP)
+
+**Done:**
+- Drizzle ORM setup with schema (projects, chats, sub_chats)
+- Auto-migration on app startup
+- tRPC routers structure
+
+**In Progress:**
+- Replacing `mock-api.ts` with real tRPC calls in renderer
+- ProjectSelector component (local folder picker)
+
+**Planned:**
+- Git worktree per chat (isolation)
+- Claude Code execution in worktree path
+- Full feature parity with web app