Alphacode

🪄 In one sentence

**Alphacode is a free, open-source AI assistant that lives on your computer and writes, fixes, tests, and explains code for you — you just tell it what you want in plain English.**

Think of it like ChatGPT, except instead of only talking about code, it actually opens your files, makes the changes, runs the tests, and tells you what it did — safely, and with your permission at every risky step.

It works with all the major AI models — Claude, GPT-4/GPT-5, Gemini, GitHub Copilot, Cursor, and others — so you're never locked into one company's AI.

🆕 I'm brand new to this. Start here.

💡 What is a "terminal," and do I need to learn one?

A terminal is just a text window where you type commands instead of clicking buttons — like a chat box, but for talking to your computer directly. It looks intimidating the first time, but you really only need to know three things to use Alphacode:

1. How to open it — every operating system has one built in (see below).
2. How to copy-paste a command — you copy a line of text from this page and paste it in. That's most of what "using the terminal" means here.
3. How to press Enter — that's it.

Once it's open, everything below just works by copy-pasting one line at a time. If something looks like an error, jump straight to Troubleshooting — every common issue has a copy-paste fix.

🧭 What is Alphacode, really? (The technical explanation)

For readers who want the precise version: Alphacode is a terminal-native AI coding agent. Give it an objective in natural language, and it:

• reads and understands your codebase,
• plans the work,
• picks the best available AI model for the job,
• edits files, runs shell commands, and executes tests,
• searches the web when it needs current information,
• coordinates multiple AI agents in parallel for large tasks,
• reviews its own work before calling anything "done,"
• and keeps the session alive — resumable, crash-safe — until the objective is genuinely complete.

Every version of that list — plain or technical — points at the same underlying rule:

### 🎯 *Make the smallest change that actually solves the problem — then verify it.*

flowchart TD
    A["🧑 You: describe what you want, in plain English"] --> B["🔎 Alphacode reads your project"]
    B --> C["🗺️ It plans the steps"]
    C --> D["🤖 It picks the best AI model for the job"]
    D --> E["🛠️ It uses tools: edit files, run commands, search the web"]
    E --> F["✅ It tests and reviews its own work"]
    F --> G["📋 It reports: what changed · what was verified · what's left"]

    style A fill:#6E56CF,color:#fff,stroke:none
    style G fill:#2CBB5D,color:#fff,stroke:none

⭐ Why people choose Alphacode

📑 Table of Contents

📥 Install Alphacode

Pick your operating system below. Each installer downloads Alphacode, checks that the download is safe and untampered (a security step called checksum verification), and sets it up automatically.

Windows

1. Open PowerShell (see how to open a terminal if you're not sure how).
2. Copy this line, paste it in, and press Enter:

iwr -useb https://raw.githubusercontent.com/dragonked2/alphacode/main/scripts/install.ps1 | iex

Optional: pin a specific version or install location

# Pin a version
iwr -useb ... | iex -Version v1.0.7

# Install into a custom folder
iwr -useb ... | iex -Prefix "$env:LOCALAPPDATA\Programs\alphacode"

# Build from source instead of downloading
iwr -useb ... | iex -FromSource

macOS / Linux

1. Open Terminal.
2. Copy this line, paste it in, and press Enter:

curl -fsSL https://raw.githubusercontent.com/dragonked2/alphacode/main/scripts/install.sh | bash

Optional settings (environment variables):

curl -fsSL https://raw.githubusercontent.com/dragonked2/alphacode/main/scripts/install.sh | bash -s -- --version v1.0.7 --prefix ~/.local

Build from source (advanced)

Only needed if you want to compile it yourself or there's no ready-made download for your exact machine type.

git clone https://github.com/dragonked2/alphacode.git
cd alphacode
cargo build --release
./target/release/alphacode --version

cargo build --release --features bedrock            # AWS Bedrock support
cargo build --release --features embeddings          # Local ONNX embeddings
cargo build --release --features pdf                 # PDF text extraction
cargo build --release --features mermaid-renderer     # Mermaid diagram rendering
cargo build --release --features bedrock,embeddings,pdf,mermaid-renderer  # all of the above

✅ Verify your install

Run these three, in order, to confirm everything worked:

# 1 — Can your computer find it?
which alphacode          # macOS / Linux
Get-Command alphacode    # PowerShell

# 2 — Is it the version you expect?
alphacode --version      # → v1.0.7 (964e49e, …)

# 3 — Is everything healthy?
alphacode doctor         # checks PATH, terminal, providers, optional dependencies

alphacode doctor prints OK, WARN, or FAIL for each check, with a fix for anything not green. If something fails, jump to Troubleshooting.

# macOS / Linux
curl -fsSL https://github.com/dragonked2/alphacode/releases/download/v1.0.7/SHA256SUMS -o SHA256SUMS
curl -fsSL https://github.com/dragonked2/alphacode/releases/download/v1.0.7/alphacode-linux-x86_64.tar.gz -o alphacode.tar.gz
sha256sum --ignore-missing -c SHA256SUMS

# Windows (PowerShell)
Invoke-WebRequest https://github.com/dragonked2/alphacode/releases/download/v1.0.7/SHA256SUMS -OutFile SHA256SUMS
$expected = (Get-Content SHA256SUMS | Where-Object { $_ -like '*windows-x86_64*' })[0].Split(' ')[0]
$actual   = (Get-FileHash .\alphacode-windows-x86_64.zip -Algorithm SHA256).Hash.ToLower()
"$expected  expected"
"$actual    actual"

⚡ Quick Start: your first 5 minutes

You don't need an account to launch Alphacode — but you need at least one AI "brain" connected so it can actually think. Pick the easiest option:

alphacode

alphacode login
alphacode login --provider openai

export ALPHACODE_OPENAI_API_KEY=sk-...
alphacode

**💡 Beginner tip:** if you're not sure which to pick, just run `alphacode` with no arguments. It works immediately using the free built-in AI — you can always switch providers later with `alphacode login`.

Launch it

alphacode

The first time, it'll ask a few quick setup questions (telemetry, default model, keyboard shortcuts). You can press Esc to skip any of them — nothing is required upfront.

Try your first task

Just describe what you want in plain sentences — no special syntax needed:

> explain what this project does in simple terms

> add a login button to my homepage

> find and fix the bug that's crashing the app

> write tests for my utils.js file

> look up the latest React release notes and summarize them

> /swarm "split this feature into 4 parallel tasks"

Handy keyboard shortcuts:

🩺 Troubleshooting — fixing common errors

Every issue below has a copy-paste fix. Find the message closest to what you're seeing.

# Bash — append to ~/.bashrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Zsh — append to ~/.zshrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Fish
fish_add_path ~/.local/bin

curl -fsSL ... | ALPHACODE_VERSION=v1.0.7 bash

rustup update stable         # macOS / Linux
# Windows: re-run rustup-init from https://rustup.rs and choose "stable"

Still stuck? Run alphacode doctor --verbose and paste the output when you file an issue. Found a security problem instead? Please report it privately via SECURITY.md rather than a public issue.

🧩 What can Alphacode actually do?

🤖 Supported AI models & providers

Alphacode doesn't lock you into one AI company. Use whichever model is best (or cheapest, or fastest) for the task at hand — and switch anytime.

Switch providers anytime, mid-conversation:

alphacode provider list              # see everything you've connected
alphacode provider current           # what's active right now
alphacode provider use openai        # make OpenAI your default
alphacode model list                 # list models for the current provider
alphacode model use gpt-4o           # pin a specific model

Or press Ctrl+T inside the app for a visual picker.

🛠 The full toolbox

Also included: PDF text extraction (optional), secure sign-in flows for every supported AI provider, and autonomous modules — a planner, project analyzer, self-review system, quality gate, and resource monitor working behind the scenes.

🎓 Built-in skills

"Skills" are ready-made expert playbooks Alphacode can follow. These ship inside the program itself, so they work everywhere, instantly:

Type /skills inside the app to browse everything available, including any custom skills you've added yourself.

🐝 Swarm Mode: multiple AI agents working together

In plain English: instead of one AI doing everything step-by-step, Swarm Mode splits a big task into smaller independent pieces, hands each piece to its own AI agent, and has them all work at the same time — like assigning different parts of a group project to different teammates, then combining everyone's work at the end.

flowchart LR
    G["🎯 Your goal"] --> P["🧭 Planner splits it up"]
    P --> A["🤖 Agent A"]
    P --> B["🤖 Agent B"]
    P --> C["🤖 Agent C"]
    P --> D["🤖 Agent D"]
    A --> M["🔀 Combine everything"]
    B --> M
    C --> M
    D --> M
    M --> R["✅ Review the result"]
    R --> X["🏁 Done"]

    style G fill:#6E56CF,color:#fff,stroke:none
    style X fill:#2CBB5D,color:#fff,stroke:none

Try it:

/swarm "split this feature into 4 parallel tasks"

You can watch the whole plan and progress live inside the app.

🛡 Safety — how Alphacode protects your computer

AI agents that can run real commands are powerful — and that power needs real guardrails. Alphacode treats safety as a first-class engineering problem, not an afterthought:

• Catastrophic targets such as rm -rf /, home-directory wipes, and device-node writes are blocked.
• Routine authorized security tooling (nmap, subfinder, nuclei, httpx, ffuf, gobuster, curl against an in-scope target) runs without a reflection prompt.
• Risky actions pass through the TUI permission layer.
• Network operations use SSRF and credential-leak heuristics only where they would actually prevent abuse; authorized testing against a target that requires your own Authorization header is supported.
• Interrupted or crashed sessions are marked instead of silently corrupting state.

Found a security vulnerability? Please report it responsibly via SECURITY.md.

🔁 Reliability — never lose your work

• alphacode --resume reopens exactly where you left off.
• alphacode sessions list shows and searches every past session.
• Crashes, dropped connections, and interruptions are clearly marked, never silently swallowed.
• Everything is saved to disk in your operating system's standard, expected location.
• Built-in health monitoring watches memory use, slow operations, and error rates during long sessions.

📊 Performance numbers

Built in Rust for a reason: speed and a small memory footprint, especially when you're running several AI sessions at once.

What makes it fast

• Compiler optimizations (opt-level = 3, thin LTO) tuned specifically for the release build.
• The performance-critical networking and interface code gets extra-focused compilation (codegen-units = 1).
• Efficient reuse of network connections instead of opening new ones repeatedly.
• Session history is stored on disk, not held entirely in memory.
• Heavy optional features are off by default, so you only pay for what you use.
• No embedded scripting language slowing things down — it's native, compiled Rust throughout.

Memory usage — historical snapshots

⚠️ **Important:** These are **legacy benchmark snapshots**, kept for historical comparison. Alphacode has improved further since these were measured — treat these as a directional illustration of architecture, not a live, current benchmark.

In plain English: a tool can look fine using one session, but memory costs multiply fast with real usage. Alphacode was designed from the start to stay lean even with many sessions running side by side.

📜 Code quality guarantees

Every code-changing action Alphacode takes follows four rules:

The source of truth lives in src/alphacode_base/prompt/system_prompt.md, enforced by the tool implementations under src/alphacode_app_core/tool/.

⌨️ Commands reference

CLI commands

alphacode                          # Launch the app
alphacode login                    # Sign in to an AI provider
alphacode login --provider openai  # Sign in to a specific provider
alphacode doctor                   # Check that everything's set up correctly
alphacode doctor --verbose         # Same, with extra detail for bug reports
alphacode provider list            # List every provider you've connected
alphacode provider add <name>      # Add a custom OpenAI-compatible endpoint
alphacode provider use <name>      # Set your default provider
alphacode provider current         # Show the active provider + model
alphacode model list               # List available models
alphacode model use <name>         # Set your default model
alphacode run "fix the failing test"   # Run one task without opening the full app
alphacode repl                     # A simple text-only mode
alphacode sessions list            # See your past sessions
alphacode --resume                 # Search for and reopen a session
alphacode --resume <id>            # Reopen one specific session
alphacode update                   # Update to the latest version
alphacode --version                # Check your current version
alphacode --help                   # See every available command

In-app slash commands

⚙️ Configuration

Alphacode keeps its settings, sessions, and logs in your operating system's standard location — never scattered inside your project folder.

The main settings file, config.toml, is created automatically the first time you run alphacode login. Full reference: docs/configuration.md.

🔄 Updating Alphacode

alphacode update

This grabs the newest version, verifies it's safe, and swaps it in — without interrupting anything you have running. You can also just re-run the original install command any time; it's safe to run repeatedly.

🗑 Uninstalling Alphacode

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/dragonked2/alphacode/main/scripts/uninstall.sh | bash

Want to remove your settings, sessions, and logs too?

curl -fsSL https://raw.githubusercontent.com/dragonked2/alphacode/main/scripts/uninstall.sh | bash -s -- --purge

Windows

iwr -useb https://raw.githubusercontent.com/dragonked2/alphacode/main/scripts/uninstall.ps1 | iex

Add -Purge to also remove settings, sessions, and logs.

🏗 Project structure

For contributors and the technically curious — here's how the codebase is organized:

alphacode/
├── src/
│   ├── alphacode_core/             # Provider-agnostic trait types and shared state
│   ├── alphacode_base/             # System prompt, prompt builder, capability enum
│   ├── alphacode_app_core/         # Agent loop, tools, autonomous layer, server
│   ├── alphacode_tui*/             # Terminal UI: rendering, widgets, style, animations
│   ├── alphacode_tool_core/        # The `Tool` trait and shared tool types
│   ├── alphacode_provider_*/       # Per-provider runtimes (Anthropic, OpenAI, …)
│   ├── alphacode_auth_*/           # Per-provider OAuth flows
│   ├── alphacode_swarm_core/       # Multi-agent coordination (task DAG, deep/light modes)
│   ├── alphacode_modules/          # High-level autonomous modules
│   └── alphacode_cli/              # The `alphacode` binary entrypoint
├── docs/                           # Architecture + configuration reference
├── scripts/                        # install / uninstall tooling
├── CONTRIBUTING.md
├── SECURITY.md
└── Cargo.toml

Deeper tour: docs/architecture.md.

🤝 Contributing

Contributions are genuinely welcome, from typo fixes to new features. Full guide: CONTRIBUTING.md. Short version:

git clone https://github.com/dragonked2/alphacode.git
cd alphacode
cargo build --release
cargo test --lib
cargo clippy --lib -- -D warnings

Requirements: Rust 1.91+ (edition 2024) and a matching C toolchain.

Before opening a pull request:

• [ ] cargo build --release passes locally
• [ ] cargo test --lib passes locally (add tests for behavior changes)
• [ ] cargo clippy --lib -- -D warnings is clean
• [ ] Public APIs have rustdoc comments
• [ ] No new dependencies unless justified in the PR description
• [ ] User-visible changes are documented in CHANGELOG.md

Security vulnerabilities: SECURITY.md. Community standards: CODE_OF_CONDUCT.md.

❓ Frequently Asked Questions

🙏 Acknowledgements

Alphacode is built on outstanding open-source projects, including:

...and many others — see Cargo.lock for the complete dependency graph.

📄 License

Alphacode is released under the MIT License — free to use, modify, and distribute. Full text: LICENSE.