Get started

Start using OpenCtrlC in the terminal and desktop app.

OpenCtrlC is an open source AI coding agent focused on terminal workflows and local development.

Let’s get started.

Prerequisites

To use OpenCtrlC in your terminal, you’ll need:

A modern terminal emulator like:
- WezTerm, cross-platform
- Alacritty, cross-platform
- Ghostty, Linux and macOS
- Kitty, Linux and macOS
API keys for the LLM providers you want to use.

Install

The easiest way to install OpenCtrlC is through the install script.

  curl -fsSL https://raw.githubusercontent.com/ponponon/openctrlc/dev/install | bash

You can also install the CLI through npm (requires Node.js and npm):

npm install -g openctrlc

If you installed the former npm package name, run npm uninstall -g openctrlc-ai before installing openctrlc.

On macOS and Linux, you can also install through the project Homebrew tap:

brew install ponponon/tap/openctrlc

For platform-specific packages, download the latest binary from the Releases page.

With OpenCtrlC you can use any supported LLM provider by configuring its API key. OpenCtrlC does not bundle a hosted model service, so you choose the provider and billing arrangement that fits your workflow.

Run the /connect command in the TUI, select an LLM provider, and follow the setup guide in Providers.
```
/connect
```
Follow the selected provider’s setup guide and copy its API key.
Paste your API key.
```
┌ API key
│
│
└ enter
```

You can select another provider at any time. See the provider directory.

Initialize

Now that you’ve configured a provider, you can navigate to a project that you want to work on.

cd /path/to/project

And run OpenCtrlC.

openctrlc

Next, initialize OpenCtrlC for the project by running the following command.

/init

This will get OpenCtrlC to analyze your project and create an AGENTS.md file in the project root.

This helps OpenCtrlC understand the project structure and the coding patterns used.

Usage

You are now ready to use OpenCtrlC to work on your project. Feel free to ask it anything!

If you are new to using an AI coding agent, here are some examples that might help.

Ask questions

You can ask OpenCtrlC to explain the codebase to you.

How does authentication flow through @src/auth/session.ts?

This is helpful if there’s a part of the codebase that you didn’t work on.

Add features

You can ask OpenCtrlC to add new features to your project. Though we first recommend asking it to create a plan.

Create a plan

OpenCtrlC has a Plan mode that disables its ability to make changes and instead suggest how it’ll implement the feature.

Switch to it using the Tab key. You’ll see an indicator for this in the lower right corner.
```
<TAB>
```
Now let’s describe what we want it to do.
```
Add a diagnostic event when a user signs in.
First trace the existing authentication flow, then propose the smallest
implementation that preserves the current session behavior.
```
You want to give OpenCtrlC enough details to understand what you want. It helps to talk to it like you are talking to a junior developer on your team.

Give OpenCtrlC plenty of context and examples to help it understand what you want.
Iterate on the plan

Once it gives you a plan, you can give it feedback or add more details.
```
We'd like to improve the account screen using the attached design reference.
[Image #1] Keep the existing navigation and responsive behavior.
```
Drag and drop images into the terminal to add them to the prompt.

OpenCtrlC can scan any images you give it and add them to the prompt. You can do this by dragging and dropping an image into the terminal.
Build the feature

Once you feel comfortable with the plan, switch back to Build mode by hitting the Tab key again.
```
<TAB>
```
And asking it to make the changes.
```
Sounds good! Go ahead and make the changes.
```

Make changes

For more straightforward changes, you can ask OpenCtrlC to directly build it without having to review the plan first.

Trace how a signed-in user reaches the session API. Identify the existing
boundary between authentication and session creation, then suggest a focused
change without duplicating request handling.

You want to make sure you provide a good amount of detail so OpenCtrlC makes the right changes.

Undo changes

Let’s say you ask OpenCtrlC to make some changes.

Can you refactor the session handler in @src/api/session.ts?

But you realize that it is not what you wanted. You can undo the changes using the /undo command.

/undo

OpenCtrlC will now revert the changes you made and show your original message again.

Can you refactor the session handler in @src/api/session.ts?

From here you can tweak the prompt and ask OpenCtrlC to try again.

Or you can redo the changes using the /redo command.

/redo

The conversations that you have with OpenCtrlC can be shared with your team.

/share

This will create a link to the current conversation and copy it to your clipboard.

You can share a conversation with your team using the /share command.

Customize

And that’s it! You are now a pro at using OpenCtrlC.

To make it your own, we recommend picking a theme, customizing the keybinds, configuring code formatters, creating custom commands, or playing around with the OpenCtrlC config.