Skip to content
Tarsk

Quickstart

import { Steps } from ‘@astrojs/starlight/components’;

This guide walks through the complete first-run experience: launching Tarsk, completing onboarding, connecting a repository, creating a branch, and sending your first message to the AI agent.

Prerequisites

Section titled “Prerequisites”

  1. Launch Tarsk

    Run npx tarsk in a terminal, or open the desktop app. Tarsk starts on http://localhost:641 and the browser opens automatically.

    On first launch, the Onboarding Wizard appears.

  2. Complete the Onboarding Wizard

    The wizard has three steps:

    • Git Check — Tarsk checks whether git is installed. A green checkmark means you’re good. If you see a yellow warning, install git from git-scm.com and refresh.

    • Provider Setup — Select your preferred AI provider from the dropdown and paste your API key. You can skip this step and configure providers later in Settings, but you’ll need at least one key before chatting.

    • Model Selection — After entering a key, the wizard loads available models for your chosen provider. Check the boxes next to the models you want to use. You can change this at any time in Settings.

    Click Finish to dismiss the wizard. Triple-click Settings in the settings sidebar to run it again.

  3. Create your first project

    On the projects home screen, use one of these options:

    • Connect a repo (welcome card) or Git Repo (sidebar + menu) — paste a git URL and clone
    • New App — scaffold from a template (React, Next.js, Vue, Svelte, and more)
    • Open Folder — connect an existing local directory
    • Blank Starter (sidebar + menu) — empty workspace folder

    If the repository has a common setup script (like npm install or bun install), a confirmation dialog appears — click Run to execute it automatically.

  4. Create a branch

    Select your project to open the project landing view, then create a branch (Tarsk’s term for an isolated thread workspace):

    • Click Branches in the chat footer and press +, or
    • Press ⌘⇧T

    Tarsk creates a fresh clone of the repository in its own directory, checks out a new git branch, and opens the chat view.

    Each branch is completely independent. You can create as many as you want on the same project and work on them simultaneously.

  5. Send your first message

    Type a message in the chat input at the bottom of the screen and press Enter. For example:

    “What does this project do? Summarise the main entry point.”

    The AI agent streams its response in real time. It can read files, run commands, search the codebase, and more. Watch the tool call indicators to see what it’s doing.

  6. Open in your IDE

    Click Open in in the chat header to open the branch directory in VS Code, Cursor, Windsurf, Xcode, Android Studio, Kiro, Devin Desktop, Antigravity, or a terminal. Your preferred editor is remembered for next time.

  7. Explore the chat dock

    Use the window taskbar at the bottom of the chat area to open Files, Terminal, Browser, Tasks, or Review alongside chat. See Chat Dock.

  8. Explore Settings

    Open settings from:

    • The gear icon on the projects home screen
    • The Settings icon in the chat header (project settings)
    • ⋯ More options in the chat header (project and general settings, providers, account)

    See Settings Overview.

What’s Next

Section titled “What’s Next”
  • Working with Threads — manage multiple parallel workstreams
  • Chat Dock — open Files, Terminal, Browser, and other panels alongside chat
  • Tasks — plan work and hand it to the agent
  • Desktop App — macOS menu bar app and auto-updates
  • VS Code Extension — use Tarsk inside your editor
  • Slack — control Tarsk from Slack channels
  • Dev Server — run and preview your app while the agent works
  • Providers & Models — add more API keys and enable specific models
  • Skills — extend the agent with custom tools and domain knowledge