1. Home
2. Docs
3. Getting Started

Getting Started

Install

CodeAlta is distributed as a .NET global tool. The package id is CodeAlta; the installed command is alta.

Install .NET 10 first, then install/update CodeAlta:

dotnet tool install -g CodeAlta

Then launch the terminal UI:

alta

CodeAlta stores user state under ~/.alta/, including configuration, logs, cached provider state, session journals, saved prompts, plugins, and skills.

Terminal font requirement

First launch

On first launch, CodeAlta creates a starter ~/.alta/config.toml with common provider entries disabled. If no provider is enabled yet, the app opens the Model Providers dialog automatically.

Use the dialog to:

1. Select a provider entry on the left.
2. Enable it.
3. Choose or confirm the model and reasoning effort.
4. Add credentials through an API-key environment variable, direct API key, or provider login flow.
5. Click Test to validate credentials and model discovery.
6. Click Save to write ~/.alta/config.toml and refresh the runtime.

You can reopen this dialog any time with Ctrl+G Ctrl+R or from the provider summary in the footer.

Configure one provider quickly

The most common first setup is a subscription-backed provider: Copilot for GitHub Copilot subscriptions, or Codex for ChatGPT/Codex subscriptions. In the Model Providers dialog, enable the matching provider, keep or choose a model, start the browser/device login flow, then click Test and Save after login completes.

Codex and Copilot credentials are stored in CodeAlta-owned state through their login flows. They are intentionally separate from OpenAI platform API keys.

If you use an API-key provider instead, set the provider's environment variable and enable that provider in the dialog or TOML. For OpenAI platform access:

# macOS/Linux
export CODEALTA_OPENAI_API_KEY="..."

# PowerShell
$env:CODEALTA_OPENAI_API_KEY = "..."

In ~/.alta/config.toml:

[chat]
default_provider = "openai"

[providers.openai]
enabled = true
display_name = "OpenAI"
type = "openai-responses"
model = "gpt-5.5"
reasoning_effort = "high"
api_key_env = "CODEALTA_OPENAI_API_KEY"
api_url = "https://api.openai.com/v1"

The in-app dialog edits the same file and preserves advanced TOML values.

Other API-key providers use the same pattern with their own environment variables, such as CODEALTA_ANTHROPIC_API_KEY, CODEALTA_DEEPSEEK_API_KEY, or CODEALTA_ZAI_API_KEY.

Send a first prompt

1. Open a project with Ctrl+O, /open, or the + button in the Projects sidebar row.
2. Select the provider/model/reasoning combination in the footer if needed.
3. Type a prompt in the prompt editor.
4. Press Enter to send. Use Shift+Enter for a new line.
5. Watch the timeline for reasoning/status messages, assistant messages, tool calls, tool results, statistics, and modified-file summaries.

Useful first prompts:

Summarize this repository and identify the main build/test commands.

Inspect the failing test output below and propose the smallest safe fix.

Add files to a prompt

Type @ in the prompt editor to open the project file/folder picker. Accepted entries are inserted as Markdown links such as [Program.cs](src/CodeAlta/Program.cs) and are sent as structured attachments. Raw @path, quoted paths, and optional :line or :start-end suffixes are also recognized at send time.

Add images to a prompt

When the selected model supports image input, copy an image to the clipboard and press Ctrl+V in the prompt editor. CodeAlta opens a preview/title dialog so you can confirm the image before it is attached, then stores the image beside the session journal.

Essential shortcuts

{ "keys": "ctrl+v", "id": "unbound" },
{ "keys": "alt+left", "id": "unbound" },
{ "keys": "alt+right", "id": "unbound" }