Yocoder

A Mac desktop app for agentic coding with Claude Code integration. Manage coding tasks with a Kanban board, execute Claude Code in isolated git worktrees, and handle multiple Claude accounts.

Features

• Kanban Board — Organize tasks with drag-and-drop, group into Epics/Rocks
• Claude Code Execution — Run Claude in isolated git worktrees per task
• Git Worktree Isolation — Each task gets its own branch and worktree
• Real-time Streaming — Watch Claude's output live via SSE
• Multiple Claude Accounts — Switch between accounts to avoid rate limits
• Context Management — Edit CLAUDE.md and project context files
• Built-in Terminals — xterm.js terminals for manual commands
• Workflow Actions — AI-assisted commits, test, merge workflow

Screenshots

Coming soon

Requirements

• macOS (PyWebView desktop app)
• Python 3.11+
• Node.js 18+
• Claude Code CLI — Install from claude.ai/code

Quick Start

1. Clone the Repository

git clone https://github.com/bvdr/yocoder.git
cd yocoder

2. Install Dependencies

# Create and activate virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate

# Install Python dependencies
pip install -e ".[dev]"

# Install frontend dependencies
cd frontend && npm install && cd ..

3. Run Development Server

./scripts/run_dev.sh

This starts:

• Backend API: http://127.0.0.1:8765
• Frontend: http://127.0.0.1:5173

4. (Optional) Build Mac App

./scripts/build_mac.sh

The app bundle will be created in dist/Yocoder.app.

Project Structure

yocoder/
├── backend/                 # Python FastAPI backend
│   ├── api/                # REST API endpoints
│   ├── claude/             # Claude profile management
│   ├── database/           # SQLite models and connection
│   ├── services/           # Business logic (execution, worktrees)
│   ├── terminal/           # PTY and WebSocket handling
│   └── main.py            # FastAPI app entry point
├── frontend/               # React + TypeScript frontend
│   ├── src/
│   │   ├── components/    # UI components (kanban, layout, settings)
│   │   ├── stores/        # Zustand state management
│   │   └── lib/           # Utilities
│   └── components.json    # shadcn/ui config
├── scripts/               # Build and dev scripts
├── build/                 # PyInstaller config and icons
└── documentation/         # Additional docs

Tech Stack

Layer	Technology
Desktop	PyWebView + PyInstaller
Backend	FastAPI, aiosqlite, SQLite
Frontend	React 18, TypeScript, Vite
UI Components	shadcn/ui, Tailwind CSS
State	Zustand
Terminals	xterm.js, node-pty

Configuration

Yocoder stores data in:

• Database: ~/Library/Application Support/Yocoder/yocoder.db
• Task Worktrees: .yocoder/worktrees/task-{id}/
• Execution Logs: .yocoder/execution_logs/task-{id}.log
• Task Specs: .yocoder/specs/task-{id}/

Environment Variables

Variable	Description	Default
YOCODER_HOST	Backend host	127.0.0.1
YOCODER_PORT	Backend port	8765

Claude Code Setup

Yocoder requires the Claude Code CLI to execute tasks.

1. Install Claude Code from claude.ai/code
2. Run claude login to authenticate
3. Add projects in Yocoder and start creating tasks

Multiple Accounts

Yocoder supports multiple Claude accounts to work around rate limits:

• CLI Auth — Uses default ~/.claude directory
• Custom Profile — Uses CLAUDE_CONFIG_DIR for separate profiles
• API Key — Direct Anthropic API key (for API access)

Development

Scripts

# Start dev server (backend + frontend)
./scripts/run_dev.sh

# Build frontend only
cd frontend && npm run build

# Build Mac app
./scripts/build_mac.sh

# Build DMG installer
./scripts/build_dmg.sh

# Clean build (removes artifacts first)
./scripts/clean_build.sh

API Documentation

See .claude/api.md for the complete REST API reference.

Architecture

See .claude/architecture.md for data flow diagrams and design decisions.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

MIT License — see LICENSE for details.

Acknowledgments

• Claude Code by Anthropic
• shadcn/ui for UI components
• FastAPI for the backend framework