# Get started with Koder

**[Koder](https://www.aixplain.com/koder)** is aixplain's AI coding agent for your desktop and terminal. Describe the change you want in plain language, and Koder reads your code, makes edits you review line by line, runs your tests and asks before anything risky. This article explains how to start a task, plan before you build, review and commit changes, connect the model you want, extend Koder with MCP servers, skills and plugins, use it from the terminal and in CI and what it can't do yet.

> Koder runs in the aixplain desktop app on macOS (Apple silicon and Intel), Windows x64 and Linux x64, and in the terminal on macOS, Windows x64 and Linux (x64 and arm64). It is free to download, and you pay only for the models you use. Koder is in early releases (version 0.x), so features and commands can change from one release to the next.

## What is Koder?

Koder is a model connected to your project through tools it can use, permissions it has to follow and a history it carries from one step to the next. It can search and read files, edit code and run commands and tests. It uses what it learns from each result in the next step.

You follow every step, answer its questions, stop it at any time and review the diff before you keep anything. Your sessions and settings stay on your computer.

### Key capabilities

- **Desktop and terminal:** the same agent, permissions and sessions in the aixplain desktop app and in a terminal app, plus a `koder` CLI for scripts and CI.
- **Plan first:** a planning agent thinks a change through before any code changes.
- **Review and diffs:** every change in a session collected in one diff, unified or split, ready to commit.
- **Sessions across projects:** one sidebar for every project's sessions, with what is running or waiting on you at the top.
- **Your choice of model:** aixplain models, a Claude, ChatGPT or Cursor plan you already pay for, your own provider or a local model.
- **Extensions:** project instructions in `AGENTS.md`, MCP servers, skills and plugins.

To find likely security bugs in a repository, see **[Find security issues with Scan](https://www.aixplain.com/support/articles/find-security-issues-with-scan)**.

## Install Koder

Koder comes with the aixplain desktop app. Download it from **[aixplain.com/koder](https://www.aixplain.com/koder#download)** and open **aixplain**. For every installer and the steps for each computer, see **[Get started with aixplain Desktop](https://www.aixplain.com/support/articles/get-started-with-aixplain-desktop)**.

The first time Koder runs, it asks you to sign in to aixplain. Signing up is free, with no card needed. Then pick a model in the model picker.

### Install the CLI

To use Koder in your terminal instead, or as well, install the `koder` CLI. It runs on macOS (arm64 and x64), Linux (arm64 and x64) and Windows x64.

On macOS and Linux:

```sh
curl -fsSL https://github.com/aixplain/koder/releases/latest/download/install | bash
```

On Windows, in PowerShell:

```powershell
irm https://github.com/aixplain/koder/releases/latest/download/install.ps1 | iex
```

The installer places `koder` in `~/.koder/bin` and adds it to your user PATH. Open a new terminal after installation.

> **Note:** To read the installer before you run it, download **[install](https://github.com/aixplain/koder/releases/latest/download/install)** or **[install.ps1](https://github.com/aixplain/koder/releases/latest/download/install.ps1)**. For archives and earlier versions, see **[all releases](https://github.com/aixplain/koder/releases)**. Every release includes a `SHA256SUMS` file for checksum verification.

## Start a task

1. Open the desktop app and select **Koder**.
2. Open a project folder.
3. Describe a task in plain language, or pick a starter.
4. Follow the steps, answer its questions and stop it at any time.

The starters are: explain this project, find and fix a bug, add a feature, write tests, review my changes or start from a pull request.

Give Koder a concrete task. Say what done looks like and any constraints, then follow the steps and review the diff.

> **Note:** Pick how much Koder does on its own from the **Permissions** menu in the chat box: **Ask first**, **Auto** or **Full access**. Even in **Full access**, Koder asks before it pushes code, deletes folders, force-deletes files, spends money or reads secret files.

### Example requests

- "Explain this project."
- "Find why this test fails, explain the cause, make the smallest fix and run the relevant tests."
- "Add a CSV export to the reports page and write tests for it."
- "Review my changes before I open a pull request."

## Plan before you build

To think a change through before any code changes, ask Koder to plan first. The planning agent works out the approach, and you let it build once the plan looks right.

In the terminal, `koder run --agent plan "<your task>"` does the same from the shell.

## Review and commit changes

The **Review** panel gathers everything the session changed, so you can read it before you commit.

1. Open the **Review** panel.
2. Read the diff, unified or split.
3. Commit from the app when you are happy with the changes.

## Work with source control

Connect GitHub, GitLab, Forgejo or Gitea, Bitbucket or Azure DevOps to work with your repositories from the app.

- **Clone and publish:** clone a repository, or publish a project as a new one.
- **Pull requests:** open a pull request, or start a chat from one with its review comments.
- **Worktrees:** work in one worktree per chat, so chats don't change each other's files.

> **Note:** Source-control tokens are kept in your system keychain.

## Find your sessions

The sidebar holds the sessions from all your projects. Anything running or waiting on you sits at the top with a short status such as "running 4m" or "waiting for you". The rest can be grouped by date or by project, or narrowed to one project.

Archived chats can be reopened from **Find a chat → Archived**. To bring sessions from a share file or another coding agent, run `koder import`.

## Use your Claude, ChatGPT or Cursor plan

If you already pay for Claude, ChatGPT or Cursor, you can use that plan in Koder. Koder runs each vendor's own CLI with the sign-in you already have, so there are no new keys to manage.

| Plan | What you need | How it runs |
| --- | --- | --- |
| **Claude** (Pro, Max, Team) | [Claude Code](https://claude.ai/download), signed in | A full Claude Code agent. Its tool use goes through Koder's permissions |
| **ChatGPT** (Plus, Pro, Business) | [Codex CLI](https://github.com/openai/codex), signed in with `codex login` | Codex with the models your plan offers |
| **Cursor** (paid plan) | Cursor's `cursor-agent`, signed in with `cursor-agent login` | Cursor's agent over ACP |

1. Install the vendor's CLI from the table above, on the same computer as Koder.
2. Sign in to it with your plan's account.
3. Open Koder. It finds installed CLIs automatically, including ones behind version managers.
4. Pick the plan's model in the model picker.

To check where each plan stands, open **Settings → Models & providers → Your subscriptions**, or run `koder providers subs`. Each plan shows as **Ready**, **Not signed in** or **Not installed**, with your account and plan, and the one command that fixes it.

> **Important:** With a Claude plan, Claude Code runs as a full agent, but its tool use still goes through Koder's permissions. Your access mode and permission rules apply to it as they do to any other model.

Usage on a connected plan counts against that plan's limits, not your aixplain credits. The usage page shows your Koder, Claude Code and Codex usage together, with your plan limits. Each limit window says whether you are ahead of it, behind it or on pace. Which models you can pick depends on what your plan offers.

## Extend Koder

You can extend Koder with project instructions, MCP servers, skills and plugins, in the desktop app and the `koder` CLI. Workspace trust decides which projects' own configuration Koder honors.

### Give a project its instructions

Put instructions that every session in a project should follow in an `AGENTS.md` file in your repository. Use it for the things you'd otherwise repeat in every chat, such as how to run the tests or which conventions to follow.

### Add MCP servers

Add and remove MCP servers from the desktop app, or manage them in the terminal with `koder mcp`.

- **Permissions apply:** in **Ask first**, MCP actions ask before they run, like any other change.
- **Large catalogs:** when your MCP servers expose many tools, Koder searches them on demand instead of sending every tool's description on every request.
- **Hung servers:** MCP tool calls are limited to 5 minutes by default, so a server that stops answering can't stall a turn.

Koder can also act as an MCP server, so other agents can start and read Koder sessions. Each one signs in with a pairing code and gets a scope it can never exceed: read only, ask, auto or full. The server holds each client to its scope.

### Create and install skills

A skill gives Koder reusable instructions for a kind of task.

1. In the desktop app, describe the skill you want.
2. Koder drafts the skill, checks it and saves it.
3. Try it before saving, or share it with your aixplain workspace.

You can also start from an uploaded `SKILL.md`. In the terminal, `koder skill` creates, checks, browses and installs skills. Skills shared with your aixplain workspace are available in Omni too.

> **Note:** Skill, command and agent files are read as data only. Their frontmatter can't run code.

### Add plugins

Add plugins to extend Koder. A project's configuration must pin each plugin to a version. Your own user configuration can leave a version unpinned, and Koder warns you when it does.

> **Important:** A plugin can allow or deny a permission before you're asked, or leave the decision to the prompt. It runs after your configured rules, so it can never override a deny.

### Choose which projects to trust

Use `koder trust` to choose the directories that may contribute configuration. Trust follows the real path of a folder. In a folder you haven't trusted:

- Opening the repository can't turn off the sandbox.
- Browser control and device control are ignored.

> **Important:** Changes to the folders that define agents, modes and commands always ask first, however the path is spelled.

## Use Koder in the terminal

The Koder terminal app has the same agent, permissions and sessions as the desktop app, with keyboard and mouse control.

- **Inline diffs:** edits show as diffs in the conversation.
- **A side panel:** tracks context, spend, changed files and tool use.
- **Offline highlighting:** code is highlighted without downloading anything while it runs.
- **Steering:** steer a running turn with Ctrl + O without stopping its background commands. Stop and Esc still stop them.
- **Pull request checks:** `/pr` watches a pull request's checks and wakes the chat when they pass or fail, when the pull request is merged or closed, or when new comments arrive.

### Sign in and start a session

1. Open a terminal in your project folder.
2. Run `koder login` to sign in to aixplain, and `koder whoami` to check the account.
3. Run `koder models` to see the models you can use.
4. Run `koder` to open the terminal app in the current project.
5. Describe a task, follow the steps and review the diff.

```sh
cd your-project
koder login
koder
```

### Set how much Koder does on its own

Switch autonomy with `/auto` followed by a level: `ask`, `rules`, `read-only`, `auto` or `full`.

- **`ask`:** commands, file changes and network calls wait for your approval.
- **`rules`:** follows your permission rules only. The default rules allow commands and edits.
- **`auto`:** works on its own within Auto's limits. When it refuses something, such as a push, it says what is outside Auto and how to allow it.
- **`full`:** works without asking, with the exceptions below.

> **Important:** Even in `full`, Koder asks before pushing, deleting folders, force-deleting files, spending money and reading secret files. Files such as `.env` always ask before they are read, including reads inside shell commands like `cat`, `grep` or `source`.

Run `koder inspect` to see the effective permission policy and which layer set each value.

### Commands

| Command | What it does |
| --- | --- |
| `koder` | Open the terminal app in the current project. |
| `koder run "Explain this project"` | Run a prompt from the shell. Add `--agent plan` to plan first, or `--model <provider/model>` to pick a model. |
| `koder omni` | Open Omni in the terminal. |
| `koder providers subs` | Check your Claude, ChatGPT and Cursor plans. |
| `koder models --zdr` | List models the catalog reports as zero data retention. |
| `koder session list` | List saved sessions. |
| `koder import` | Import sessions from a share file or another coding agent. |
| `koder mcp` | Manage MCP servers. |
| `koder skill` | Create, check, browse and install skills. |
| `koder trust` | Choose the directories that may contribute configuration. |
| `koder inspect` | Show the effective permission policy and which layer set each value. |
| `koder pair` | Pair a phone or tablet with this computer. |
| `koder stats` | Show token usage and cost. |
| `koder billing` | View credits, top up or add a card. |
| `koder doctor` | Check the install, config, storage, providers and recent logs. |
| `koder report` | Save a bug report with the session, recent logs and version. |
| `koder serve` | Start a headless server for clients and integrations. |
| `koder upgrade` | Update the CLI. |

Run `koder --help` or `koder <command> --help` for every command and option in your installed version.

`koder serve` bound to anything other than your own machine (a non-loopback address) needs a password of at least 12 characters.

### Where Koder keeps its files

| What | Where |
| --- | --- |
| Project instructions | `AGENTS.md` in your repository |
| Global configuration | `~/.config/koder/koder.json` or `koder.jsonc` |
| Sessions and other local state | `~/.local/share/koder` |

XDG environment settings can change these paths.

### Update the CLI

```sh
koder upgrade
koder --version
```

Upgrading keeps your sessions, saved permissions, schedules and theme. The `aixplain-code` command remains available as a compatibility alias. The desktop app checks for updates itself.

## Run Koder in CI

`koder run` takes a prompt from the shell, so you can run the agent in scripts and CI. It waits for background work to finish before it exits.

```sh
koder run "Explain this project"
koder run --agent plan "Plan how to add a CSV export to the reports page"
koder run --model <provider/model> "Summarize the changes on this branch"
```

- **A supported runner:** one of the CLI platforms, with `curl` and `bash` on macOS and Linux, or PowerShell on Windows.
- **A model the job can use:** set it up as you would on your computer, with aixplain models, your own provider or a local model.
- **Install in the job:** use the install commands above. A CI step that runs in the same shell may not see the new PATH, so call `~/.koder/bin/koder` directly or add that folder to the job's PATH.
- **Pin a version:** download the installer from that release's page on **[GitHub](https://github.com/aixplain/koder/releases)** instead of `latest`.
- **Check the job:** run `koder doctor` to check the install, config and providers, and `koder inspect` to see the effective permission policy.

## Pricing and usage

Koder is free to download. What you pay depends on the model:

- **aixplain models** draw on your team's credits. One credit is one US dollar.
- **A connected Claude, ChatGPT or Cursor plan** counts against that plan's limits.
- **Your own provider** bills you directly.
- **Local models** cost nothing beyond your hardware.

The Core plan costs $0 a month and includes access to Koder. For plans, see **[Pricing](https://www.aixplain.com/pricing)** and **[Account, plans and billing](https://www.aixplain.com/support/articles/account-plans-and-billing)**.

## Privacy and data

- **Stored on your computer:** your projects, sessions and settings stay on your machine.
- **Sent to the model you choose:** the parts of your code a task needs go only to the selected model. Pick a local model or a zero data retention model when that matters.
- **Secret files ask first:** files such as `.env` always ask before they are read, in every mode.
- **Crash reports:** off by default, and they never include your code.

For more, see **[Privacy and data](https://www.aixplain.com/support/articles/privacy-and-data)**.

## Limitations

- Hosted models, connected apps and sign-in need a network connection.
- The desktop app isn't available for Linux on Arm yet. The CLI and terminal app are.
- A Claude, ChatGPT or Cursor plan needs that vendor's CLI installed and signed in on the same computer.
- This article doesn't list every flag or each CI system's own setup. Run `koder <command> --help` for the options in your installed version.

## Frequently asked questions

### Do I need an aixplain account?

Koder asks you to sign in to aixplain the first time it runs. Signing up is free, with no card needed. Then use aixplain models, connect a provider with your own credentials or run a local model.

### What's the difference between Koder and aixplain Desktop?

aixplain Desktop is the app you install. Koder is its coding mode, next to Design and Omni. Koder also runs in your terminal through the `koder` command. See **[Get started with aixplain Desktop](https://www.aixplain.com/support/articles/get-started-with-aixplain-desktop)**.

### Which models can I use?

aixplain's catalog of hosted models, including open-weight models; your Claude, ChatGPT or Cursor plan; providers you connect with your own key or any chat-completions-compatible endpoint; and local models through Ollama or the built-in engine.

### Does it work offline or fully locally?

Your sessions and settings are always stored on your machine, and with a local model the model runs there too. Hosted models, connected apps and sign-in need a network connection.

### Which platforms does it support?

The desktop app runs on macOS (Apple silicon and Intel), Windows x64 and Linux x64 (DEB, RPM and AppImage). The CLI and terminal app also run on Linux arm64.

### Can I build and deploy agents with Koder?

Yes. Your developers build agents with Koder and the Agents SDK, in your own codebase, then test them and deploy each one on cloud, where it runs 24/7, or on your own servers. See **[Build and deploy agents](https://www.aixplain.com/support/articles/build-and-deploy-agents)**.

### Can I follow Koder from my phone?

Yes. Run `koder pair` to pair a phone or tablet with your computer, on your network or from anywhere through an encrypted relay. You can then follow chats, answer questions and approve steps. See **[Pair your phone or tablet](https://www.aixplain.com/support/articles/get-started-with-aixplain-desktop#pair-your-phone-or-tablet)**. A phone can never raise a chat to **Full access**.

### Which languages does the app support?

The desktop app is available in 17 languages, including Arabic with a right-to-left layout.

### Why doesn't my Claude, ChatGPT or Cursor plan show up?

Make sure the vendor's CLI is installed and signed in (Claude Code, `codex login` or `cursor-agent login`), then check **Settings → Models & providers → Your subscriptions** or run `koder providers subs`. If a plan shows **Not signed in**, sign in to that vendor's CLI in a terminal and check again.

### Why isn't koder found after I install it?

Open a new shell, or add `~/.koder/bin` to your PATH. In CI, call `~/.koder/bin/koder` directly or add that folder to the job's PATH.

### Why can't my CI job reach a model?

Run `koder doctor` in the job. It checks the install, config, storage, providers and recent logs.

## Get help

- **Fix a problem:** see **[aixplain Desktop troubleshooting](https://www.aixplain.com/support/articles/aixplain-desktop-troubleshooting)**, or run `koder doctor` to check the install, config, providers and recent logs.
- **Report a bug:** open an issue on **[GitHub](https://github.com/aixplain/koder/issues/new/choose)** with your version, operating system, the steps to reproduce it and what you expected. `koder report` saves a bug report with the session, recent logs and version.
- **Report a security issue:** email **care@aixplain.com**.
- **See what changed:** read the **[release notes](https://www.aixplain.com/release-notes)**.