Documentation Index
Fetch the complete documentation index at: https://mintlify.com/21st-dev/1code/llms.txt
Use this file to discover all available pages before exploring further.
Get your first agent running in 3 steps
This guide will help you install 1Code, create your first chat session, and run an AI coding agent on your local project.Download and install 1Code
Choose your installation method:
- Download (Recommended)
- Build from Source
Visit 1code.dev and download the pre-built app for your platform:macOS Installation:
- macOS: Download the DMG (Apple Silicon or Intel)
- Windows: Download the installer (coming soon)
- Linux: Download AppImage or DEB (coming soon)
Pre-built releases include automatic updates and support for background agents. Your subscription helps maintain and improve 1Code.
- Open the downloaded DMG file
- Drag 1Code to your Applications folder
- Launch 1Code from Applications
- If you see a security warning, go to System Preferences → Security & Privacy and click Open Anyway
Create your first chat session
When you first launch 1Code, you’ll be prompted to:
- Select a project folder - Choose any local Git repository or project directory
- Configure your API keys - Add your Anthropic API key for Claude, or OpenAI key for Codex
- Click Settings → API Keys
- Enter your API key and save
- Start a new chat - Click the New Chat button or press
Cmd/Ctrl + N
Run your first agent
Now let’s give your agent a task!Try these example prompts:Watch your agent work:
- See real-time tool execution (bash commands, file edits)
- Review diffs before they’re applied
- View file changes with syntax highlighting
- Approve or reject changes
Each chat runs in its own Git worktree by default, keeping your main branch safe. You can disable this in settings if you prefer.
What’s next?
Now that you have 1Code running, explore these powerful features:Git Worktree Isolation
Run agents in isolated worktrees without touching your main branch.
Plan Mode
Let agents ask clarifying questions and show plans before execution.
Background Agents
Run agents in cloud sandboxes that work while you sleep.
MCP Integration
Connect external tools and data sources to your agents.
Common first-run issues
Agent binary not found
Agent binary not found
Error: “Claude binary not found” or “Codex binary not found”Solution: If you built from source, make sure you ran the download scripts:The binaries should be in
resources/bin/ after download.API key not working
API key not working
Error: “Invalid API key” or authentication failuresSolution:
- Verify your API key is correct in Settings → API Keys
- Check your API key has sufficient credits/quota
- For Anthropic, ensure you’re using a valid Claude API key (not Console key)
macOS security warning
macOS security warning
Error: “1Code can’t be opened because it is from an unidentified developer”Solution:
- Go to System Preferences → Security & Privacy
- Click Open Anyway next to the 1Code warning
- Confirm you want to open the app
Python build errors
Python build errors
Error: Build fails with Python-related errorsSolution:
- Ensure Python 3.11+ is installed:
python --version - Install setuptools:
pip install setuptools - On Python 3.12+, setuptools is required for native module rebuilds
Need more help?
Join our Discord community for support and discussions.