dragonked2/alphacode

AlphaCode — Open-Source Rust AI Coding Agent

A terminal-first AI coding agent that understands your codebase, edits files, runs commands and tests, automates Firefox, controls desktop applications, and verifies its own work.

Get started · Documentation · Releases · Report a bug · Firefox Browser Agent

Preview AlphaCode in action, from installation to a first task. Click the image to open the original SVG at full size.

_{The image links to the original SVG. If it does not render in a third-party viewer, open the SVG directly.}

AlphaCode is an open-source AI coding agent built in Rust. Instead of only suggesting code in a chat, it works directly in your development environment: it can inspect a repository, plan a task, edit files, run commands and tests, use web tools, operate a real Firefox session, interact with desktop applications, and report what it verified.

flowchart LR
    A["Describe a goal"] --> B["Understand the project"]
    B --> C["Plan the work"]
    C --> D["Act: code, web, browser, desktop"]
    D --> E["Verify with tests and evidence"]
    E --> F["Report what changed"]

The workflow follows understand → plan → execute → observe → verify, and ends with a report of what changed, what was checked, and what remains.

You can use plain-English instructions or precise technical tasks. Here are three typical requests.

Find why the app crashes when users upload a PDF.
Fix the root cause, add a regression test, run the relevant tests, and review the final diff.

Open the application in Firefox, go to the account settings page,
check that the new feature is visible, and capture a screenshot.

Trace untrusted input to sensitive operations, validate likely findings,
and report which issues are reproducible in this authorized test environment.

Advanced workflows can combine multiple agents, reusable skills, and MCP-connected tools.

Four steps from zero to your first task.

macOS / Linux

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

Windows (PowerShell)

irm https://raw.githubusercontent.com/dragonked2/alphacode/main/scripts/install.ps1 | iex

alphacode doctor
alphacode

alphacode doctor checks your environment and reports common setup issues. The built-in free AI lane lets you start without configuring an API key; connected providers may require their own credentials and may incur charges.

The first launch includes a short onboarding flow for preferences such as telemetry, model defaults, and key bindings. You can skip any step with Esc.

Type a request such as:

Explain this project and identify its main entry points.

Or ask it to investigate and repair a failing test:

Find the highest-impact bug, fix it with the smallest reasonable change, and run the relevant tests.

To run a task directly, without opening the interactive terminal UI:

alphacode run "fix the failing test"

Install the AlphaCode Browser Agent extension, then run:

alphacode browser setup
alphacode browser status

The status command reports whether the browser bridge is available and responding.

Use AlphaCode to explore an unfamiliar codebase, trace a bug, refactor a module, add a feature, run a build, create regression tests, review a diff, or investigate a failure.

Combine web tools with a real browser to inspect dynamic pages, interact with forms, validate user flows, capture screenshots, and support web application QA. Browser automation is particularly useful when a page depends on JavaScript or an existing authenticated session.

The AlphaCode Browser Agent is a Firefox extension that connects AlphaCode to a real Firefox session through native messaging. AlphaCode handles reasoning and orchestration; Firefox provides the live browser environment.

flowchart LR
    U["You"] --> A["AlphaCode agent"]
    A --> B["Browser tool"]
    B --> C["Native messaging"]
    C --> D["Browser Agent extension"]
    D --> F["Firefox"]
    F --> G["Page DOM, forms, frames, UI"]
    G --> D
    D --> A
    A --> R["Reported result"]

Browser automation can help with:

• JavaScript-heavy sites and dynamic interfaces
• DOM inspection, form entry, and interactive controls
• Tabs, frames, and embedded content
• Existing authenticated sessions
• Scrolling, navigation, screenshots, and downloads
• Browser-based testing, QA, and web application debugging
• Security testing of systems you own or are explicitly authorized to assess

Example instruction:

Open the application, test the login flow, navigate to the dashboard,
check the form validation, and report reproducible problems.

AlphaCode interacts with native applications through platform accessibility APIs rather than relying only on fixed screen coordinates.

Supported actions: list_windows, snapshot, find, click, type, press, scroll, focus, screenshot, toggle, expand, and collapse.

Example:

Open Calculator, calculate 123 × 456, and read the result.

The expected arithmetic result is 56088. Actual desktop interaction depends on a working accessibility backend and on the target application being available. If it does not work, see Desktop automation is unavailable.

Swarm mode splits a large goal into parallel or semi-independent tasks and coordinates the results.

flowchart TD
    G["Large goal"] --> P["Planner"]
    P --> A["Agent A: code analysis"]
    P --> B["Agent B: security review"]
    P --> C["Agent C: tests"]
    P --> D["Agent D: documentation"]
    A --> M["Coordinator"]
    B --> M
    C --> M
    D --> M
    M --> R["Review"]
    R --> F["Final result"]

Example command inside AlphaCode:

/swarm "Analyze this application from architecture, security, testing, and performance perspectives."

Persistent sessions preserve context across terminal restarts and support longer debugging, research, security-review, and refactoring workflows.

alphacode sessions list      # List saved sessions
alphacode --resume           # Resume the latest session
alphacode --resume <id>      # Resume a specific session

Project memory supports continuity during longer workflows. Use /memory inside AlphaCode to manage or inspect it.

AlphaCode is model-agnostic. Start with the built-in free AI lane, or connect a provider using the authentication method that provider supports.

alphacode login                    # Open the provider sign-in flow
alphacode login --provider openai  # Sign in with a specific provider
alphacode provider list            # List configured providers
alphacode provider add <name>      # Add an OpenAI-compatible endpoint
alphacode provider current         # Show the active provider and model
alphacode model list               # List available models
alphacode model use <model>        # Select a model

In the terminal UI, press Ctrl+T to open the model/provider selector.

For local servers such as LM Studio or Ollama, AlphaCode uses the context window reported by the server when available. For local models with up to 32K context, it uses a shorter task prompt and a bounded set of relevant tool schemas; simple greetings may not need tool schemas at all.

Many providers use environment variables such as ANTHROPIC_API_KEY or OPENAI_API_KEY. You can also run alphacode login from your shell, or /login inside AlphaCode.

OpenAI Codex OAuth: AlphaCode uses a local callback at http://localhost:1455/auth/callback during sign-in. Make sure port 1455 is free. If the login flow times out, check whether another process is listening on that port, then retry /login.

See the documentation for provider-specific setup and troubleshooting.

AlphaCode includes 40+ tools across the following categories. Names and availability can vary with the build and enabled features.

Skills provide reusable, specialized workflows without changing the core agent. Browse available skills with /skills. Examples from the project include /bugbounty, /meme-coin-audit, and /frontend-design.

MCP support lets you connect external tools, services, and custom integrations. See the project documentation for the configuration each server requires.

Code analysis, HTTP tools, browser automation, terminal execution, memory, and multi-agent workflows can support repeatable application-security reviews.

Example tasks:

Review this API for insecure direct object references and provide reproducible evidence.

Trace this parameter through the application and determine whether it reaches a dangerous sink.

Use the authorized test environment in Firefox to test input validation and document reproducible findings.

An agent that can change files, execute commands, and operate applications needs careful oversight. The project describes these safeguards:

• Blocking certain destructive filesystem and device targets
• Permission prompts for risky actions
• Safety controls for shell execution
• SSRF and credential-leak heuristics for network operations
• Tracking interrupted sessions rather than silently losing them
• Timeouts and emergency-stop handling for desktop automation
• Input-state cleanup when operations fail
• Treating browser and desktop content as potentially untrusted

Sessions are resumable and designed to recover from interruptions. Crashes, signals, or dropped SSH connections can mark a session as Crashed and provide a resume command. Session transcripts are persisted to disk rather than kept entirely in process memory.

For code-changing tasks, AlphaCode is instructed to follow these guardrails:

1. Small changes: avoid bundling unrelated edits; report adjacent issues separately.
2. Regression awareness: rerun relevant tests and investigate new warnings or failures.
3. Self-review: check that the objective is covered, evidence is available, regressions are considered, the diff is scoped, and edge cases are reviewed.
4. Structured reporting: state what changed, what was verified, and what remains.

The agent's instructions are not a substitute for independently reviewing the implementation and test results.

AlphaCode is written in Rust and designed to keep runtime overhead modest.

Record the following so results can be compared fairly, and compare tools under the same conditions:

• AlphaCode version or commit
• OS, CPU, and RAM
• Build profile and enabled features
• Number of concurrent sessions
• Measurement method and warm/cold state
• The exact workload

The quick-start commands use the latest installer. This section documents optional installation flags and source builds. Inspect remote scripts before running them if your environment requires manual review.

irm https://raw.githubusercontent.com/dragonked2/alphacode/main/scripts/install.ps1 | iex

The installer:

• detects your CPU architecture and downloads a release;
• verifies the release's SHA-256 checksum;
• installs alphacode.exe under %LOCALAPPDATA%\Programs\alphacode\bin\;
• adds that folder to the current user's Path and activates it in the current shell;
• needs no administrator rights for the user-level install.

Run AlphaCode from Windows Terminal or PowerShell. Do not double-click alphacode.exe; the temporary console may close when the process exits.

To pass installer parameters, load the script as a script block instead of piping directly to iex:

$installer = [scriptblock]::Create((irm https://raw.githubusercontent.com/dragonked2/alphacode/main/scripts/install.ps1))

# Pin a release version
& $installer -Version vX.Y.Z

# Build from source instead of downloading a release
& $installer -FromSource

# Preview the PATH change without writing it
& $installer -PathDryRun

# Do not modify PATH
& $installer -NoPath

# Choose a custom installation prefix
& $installer -Prefix "$env:LOCALAPPDATA\Programs\alphacode"

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

The installer downloads a release, verifies its checksum, installs alphacode under ~/.local/bin, and updates a supported shell profile so the command is available. It is documented as supporting bash, zsh, fish, nushell, csh, and ksh, and as safe to re-run without duplicating its profile entry.

# Pin a release version
curl -fsSL https://raw.githubusercontent.com/dragonked2/alphacode/main/scripts/install.sh | bash -s -- --version vX.Y.Z

# Do not modify PATH
curl -fsSL https://raw.githubusercontent.com/dragonked2/alphacode/main/scripts/install.sh | bash -s -- --no-path

# Link into /usr/local/bin
curl -fsSL https://raw.githubusercontent.com/dragonked2/alphacode/main/scripts/install.sh | bash -s -- --link

# Choose a custom installation prefix
curl -fsSL https://raw.githubusercontent.com/dragonked2/alphacode/main/scripts/install.sh | bash -s -- --prefix ~/.local

alphacode --version
alphacode doctor

On Windows, you can also check command resolution with:

Get-Command alphacode

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

The project pins Rust edition 2024 in rust-toolchain.toml. A C toolchain for your platform is also required.

The default build omits some heavier optional stacks. Enable them when you need them:

cargo build --release --features bedrock,embeddings,pdf,renderer

If you also need Azure AD authentication, add azure-auth to the feature list, for example --features bedrock,azure-auth,embeddings,pdf,renderer.

alphacode update

AlphaCode stores its configuration, sessions, and logs outside the project directory.

A health monitor records memory use, slow operations, error rates, and subsystem liveness in health.json.

See docs/configuration.md for the full reference.

Start with alphacode doctor. It catches most setup problems. Then find your symptom below.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

fish_add_path $HOME/.local/bin

alphacode browser status
alphacode browser setup

Still stuck? Run alphacode doctor and open an issue with reproducible steps and relevant logs.

Close active AlphaCode sessions first. On Windows, a running alphacode.exe cannot be removed until its process exits.

macOS / Linux

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

Windows (PowerShell)

irm https://raw.githubusercontent.com/dragonked2/alphacode/main/scripts/uninstall.ps1 | iex

By default, the uninstall scripts remove the installed executable and leave your configuration and saved sessions in place.

macOS / Linux

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

Equivalent environment-variable form:

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

Windows (PowerShell)

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/dragonked2/alphacode/main/scripts/uninstall.ps1))) -Purge

Remove only the binary to keep your settings and sessions. Delete the data directories only if you intend to remove local state as well.

Linux

rm -f ~/.local/bin/alphacode
# Optional: remove configuration, sessions, and logs
rm -rf ~/.config/alphacode ~/.local/share/alphacode

macOS

rm -f ~/.local/bin/alphacode
# Optional: remove configuration and local data
rm -rf "$HOME/Library/Application Support/alphacode"

Windows (PowerShell)

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Programs\alphacode"
# Optional: remove configuration and local data
Remove-Item -Recurse -Force "$env:APPDATA\alphacode", "$env:LOCALAPPDATA\alphacode"

If AlphaCode was installed with cargo install --path ., uninstall it with cargo uninstall alphacode. If you built from a clone, remove the cloned repository separately.

• PATH entry: remove the AlphaCode entry from your shell profile or user PATH if you no longer need it. On Windows, use the Environment Variables dialog to avoid expanding %USERPROFILE%-style entries unintentionally.
• Firefox extension: open about:addons in Firefox, select AlphaCode Browser Agent, and choose Remove.
• Native messaging registration: if you ran alphacode browser setup, remove the AlphaCode registration from the relevant Firefox native messaging location. Check the exact registration name first.
  • Linux: ~/.mozilla/native-messaging-hosts/
  • macOS: ~/Library/Application Support/Mozilla/NativeMessagingHosts/
  • Windows: HKCU\Software\Mozilla\NativeMessagingHosts
• Credentials: remove exported *_API_KEY variables and revoke provider API keys or OAuth grants you no longer need.
• Scheduled jobs: remove any recurring tasks you created with cron or schedule before deleting local application data.

command -v alphacode

On Windows:

Get-Command alphacode -ErrorAction SilentlyContinue

If the shell still finds the command, open a new terminal or refresh the shell's command cache.

• Documentation index
• Configuration reference
• Changelog
• Contributing guide
• Code of conduct
• Security policy
• Official website
• GitHub releases
• Firefox Browser Agent

Report vulnerabilities privately using the instructions in SECURITY.md. For issues specific to the Firefox extension, Mozilla's add-on reporting tools may also be appropriate.

Issues, reproducible bug reports, documentation updates, and pull requests are welcome.

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

Before opening a pull request, check the relevant items:

• Release build succeeds
• Relevant tests pass
• New behavior includes tests where appropriate
• Clippy passes
• Public APIs are documented
• New dependencies are justified
• User-visible changes are documented

Read CONTRIBUTING.md before submitting a change.

Star the repository, report reproducible bugs, suggest improvements, improve the documentation, test releases, or contribute code.