Frequently Asked Questions

General Questions

What is 1Code?

1Code is an open-source desktop application that provides a unified interface for AI coding agents like Claude Code and Codex. It offers features like git worktree isolation, visual diff previews, background agents, and MCP server integration.The app is built on Electron and runs locally on your machine, with optional cloud features available through a subscription.

Is 1Code free to use?

Yes! The open-source version is completely free. You can:

Build from source
Use local AI chat
Work with git worktrees
Use the integrated terminal
Access Claude Code and Codex integration

Subscription features (1code.dev):

Sign in / Sync across devices
Background agents that run in the cloud
Auto-updates
Private Discord support
Early access to new features
Automations (Pro/Max plans)

See CONTRIBUTING.md for the full feature comparison.

What's the difference between 1Code and Cursor/Windsurf?

1Code focuses on orchestrating multiple agents with git worktree isolation:1Code advantages:

Multi-agent support (Claude Code, Codex, custom models)
Git worktree isolation per chat (never touch main)
Background agents that run in cloud sandboxes
MCP server management UI
Plan mode with structured thinking
Open source with self-hosting option

Cursor/Windsurf advantages:

More polished IDE experience
Better inline editing
Larger community and ecosystem

What are git worktrees and why should I use them?

Git worktrees let you have multiple working directories from the same repository. 1Code creates a separate worktree for each chat session, so:

Your main branch stays clean and untouched
You can review changes before merging
Multiple agents can work in parallel without conflicts
Failed experiments don’t pollute your main codebase

Learn more in the Working with Worktrees guide.

Does 1Code work offline?

Partially. The app runs locally, but:Works offline:

All UI and local features
Terminal and file operations
Git operations

Requires internet:

Claude Code API calls (requires Anthropic API key)
Codex API calls (requires OpenRouter or other provider)
Background agents (cloud sandboxes)
MCP server installations from marketplace
Auto-updates (if using 1code.dev subscription)

Installation & Setup

What are the system requirements?

Minimum requirements:

macOS 10.15+, Windows 10+, or Linux
4GB RAM (8GB recommended)
500MB disk space
Node.js 19+ (for development only)
Bun (for development only)

For building from source:

Bun package manager
Python 3.11 (3.12+ requires setuptools)
Xcode Command Line Tools (macOS only)
Git

How do I install 1Code?

Option 1: Download pre-built app (recommended) Subscribe at 1code.dev to get pre-built releases with auto-updates.Option 2: Build from source (free)

git clone https://github.com/21st-dev/1code
cd 1code
bun install
bun run claude:download
bun run codex:download
bun run build
bun run package:mac  # or package:win, package:linux

Don’t skip the claude:download and codex:download steps! The app won’t work properly without these binaries.

Do I need my own API keys?

Yes. 1Code supports “Bring Your Own Key” (BYOK):Required API keys:

Anthropic API key (for Claude Code)
OpenRouter, OpenAI, or other provider (for Codex and custom models)

Configure API keys in Settings → Models & Providers.

Background agents (cloud sandboxes) are only available with a 1code.dev subscription and don’t require your own keys.

Can I use 1Code with my company's LLM?

Yes! 1Code supports custom models and providers:

Go to Settings → Models & Providers
Add a custom provider with your API endpoint
Configure authentication (API key, headers, etc.)
Select your custom model in the model picker

See Custom Models for detailed setup instructions.

Features & Usage

What's the difference between Plan mode and Agent mode?

Plan mode:

Agent asks clarifying questions first
Creates a structured plan before execution
You review and approve the plan
Good for complex or ambiguous tasks

Agent mode:

Agent executes immediately
Faster for straightforward tasks
Full tool permissions (bash, file edits, etc.)

Switch between modes using /plan and /agent commands.

How do background agents work?

Background agents run in isolated cloud sandboxes that continue working even when your laptop is closed.Key features:

Clone your repo to a cloud VM
Run agents with full tool access
Live browser previews of dev branches
Notification when tasks complete
Works on mobile via PWA

Requirements:

Pro or Max subscription at 1code.dev

Learn more: Using Background Agents

What are MCP servers?

MCP (Model Context Protocol) servers extend agent capabilities by connecting to external tools and services.Examples:

Database access (PostgreSQL, MySQL)
Cloud providers (AWS, GCP, Azure)
Project management (Linear, Jira)
Communication (Slack, Discord)
File systems and APIs

1Code includes:

Built-in MCP server management UI
Plugin marketplace for one-click installs
Rich tool call display with formatted I/O

See Setting Up MCP Servers for details.

Can I fork a chat to try different approaches?

Yes! Click any assistant message and select Fork Chat to create a new branch of the conversation.This lets you:

Try different approaches without losing the original
Compare results side-by-side
Experiment with different prompts

Each fork runs in its own git worktree.

How do I queue multiple prompts?

Use the message queue to send prompts while an agent is working:

Type your message in the input box
The “Send” button changes to “Queue”
Click Queue to add to the queue
The agent processes queued messages in order

This is useful for:

Adding follow-up instructions
Correcting the agent mid-task
Chaining multiple tasks

Can I use voice input?

Yes! 1Code includes hold-to-talk dictation:

Hold the Space key (or click the mic icon)
Speak your message
Release to stop recording
The transcribed text appears in the input box

Requires microphone permission. macOS will prompt on first use.

Automations & API

What are automations?

Automations trigger agents automatically based on events:Triggers:

GitHub PR comments (@1code)
Linear task mentions (@1code)
Slack messages (@1code)
Git events (push, PR, CI failures)
Manual triggers

Example use cases:

Auto-review PRs
Fix failing CI tests
Generate documentation on PR
Sync Linear tasks with code changes

Requirements:

Pro or Max subscription

Learn more: Automations Guide

Can I use 1Code programmatically?

Yes! The 1Code API lets you run agents programmatically:

curl -X POST https://1code.dev/api/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "repository": "https://github.com/your-org/your-repo",
    "prompt": "Fix the failing CI tests"
  }'

Features:

Remote sandboxes with repo cloned
Automatic PR creation
Async execution with status polling
Follow-up messages to running tasks

Requirements:

API access (Max plan)

Learn more: API Documentation

Troubleshooting

The app builds but agents don't work

You likely forgot to download the agent binaries:

bun run claude:download
bun run codex:download
bun run build

These binaries are required for Claude Code and Codex functionality.

I'm getting Python/setuptools errors

Python 3.12+ doesn’t include setuptools by default:

pip install setuptools
bun install

Or use Python 3.11 which includes setuptools.

Git worktree operations are failing

Common causes:

Uncommitted changes in main branch
Existing worktree with the same name
Corrupted git repository

Solution:

git worktree list
git worktree prune
git status

See Troubleshooting for more solutions.

Where can I get help?

Discord

Real-time community support

GitHub

Bug reports and feature requests

See Support for all support options.

Privacy & Analytics

Does 1Code collect telemetry?

Open source builds: Analytics (PostHog) and error tracking (Sentry) are disabled by default. They only activate if you set environment variables in .env.local.1code.dev builds: Basic usage analytics are enabled to help improve the product. We collect:

Feature usage (anonymized)
Error reports (via Sentry)
Performance metrics

We never collect:

Your code or file contents
API keys or credentials
Personal conversations with agents
Repository contents

Where is my data stored?

Local data:

Database: ~/Library/Application Support/1Code/data/agents.db (macOS)
Projects: In your specified local folders
Worktrees: In .git/worktrees/ of your repo

Cloud data (1code.dev subscription only):

Account info and settings
Background agent session metadata
Automation configurations

Your code never leaves your machine unless you use background agents or the API.

Can I self-host 1Code?

Yes! The entire app is open source. Build and run it locally:

git clone https://github.com/21st-dev/1code
cd 1code
bun install
bun run claude:download
bun run codex:download
bun run dev

Limitations:

No cloud features (background agents, sync, automations)
No auto-updates
You need to manage your own API keys

For cloud features, you need a 1code.dev subscription.

Still have questions?

Join Discord

Chat with the community and team

GitHub Discussions

Ask questions and share ideas

Troubleshooting

Common issues and solutions

Support

All support options

Help

Community

Frequently Asked Questions

General Questions

Installation & Setup

Features & Usage

Automations & API

Troubleshooting

Discord

GitHub

Privacy & Analytics

Still have questions?

Join Discord

GitHub Discussions

Troubleshooting

Support

Build docs developers (and LLMs) love

Help

Community

Documentation Index

​General Questions

​Installation & Setup

​Features & Usage

​Automations & API

​Troubleshooting

Discord

GitHub

​Privacy & Analytics

​Still have questions?

Join Discord

GitHub Discussions

Troubleshooting

Support

Build docs developers (and LLMs) love

General Questions

Installation & Setup

Features & Usage

Automations & API

Troubleshooting

Privacy & Analytics

Still have questions?