Skip to main content

​
Quick Start Guide

This guide will walk you through creating your account, setting up your first project, and using Polaris’s AI features.
This quickstart is for users of the hosted Polaris service. If you’re self-hosting, see the Installation Guide.

​
Prerequisites

All you need is:
  • A modern web browser (Chrome, Firefox, Safari, or Edge)
  • A GitHub account (for authentication)
  • 5 minutes of your time

​
Step 1: Create Your Account

1

Sign Up with GitHub

Navigate to the Polaris homepage and click “Sign in with GitHub”. Polaris uses Clerk for secure authentication with GitHub OAuth.
// Authentication is handled by Clerk
import { auth } from "@clerk/nextjs/server";

const { userId } = await auth();
2

Authorize Access

Grant Polaris permission to access your GitHub profile. This enables future features like repository import/export.
3

Complete Setup

You’ll be redirected to your projects dashboard at /projects. You’re now ready to create your first project!

​
Step 2: Create Your First Project

1

Open Project Dialog

Click the “New Project” button in the dashboard. You’ll see a prompt input powered by AI.
Projects in Polaris are stored in Convex with this schema:
projects: defineTable({
  name: v.string(),
  ownerId: v.string(),
  updatedAt: v.number(),
  settings: v.optional(
    v.object({
      installCommand: v.optional(v.string()),
      devCommand: v.optional(v.string()),
    })
  ),
}).index("by_owner", ["ownerId"])
2

Describe Your Project

Type what you want to build in natural language:
  • “Build a todo app with React”
  • “Create a landing page for a SaaS product”
  • “Set up a Node.js Express API”
Press Enter or click Submit. Polaris will create your project workspace.
3

Explore the IDE

Your project opens in the Polaris IDE with three main areas:
  • Left Sidebar: AI conversation panel for context-aware assistance
  • Center: File explorer and code editor with syntax highlighting
  • Top Bar: Project settings and navigation
The layout uses resizable panes powered by Allotment:
<Allotment defaultSizes={[400, 1000]}>
  <Allotment.Pane minSize={200} maxSize={800}>
    <ConversationSidebar projectId={projectId} />
  </Allotment.Pane>
  <Allotment.Pane>
    {/* Editor and file explorer */}
  </Allotment.Pane>
</Allotment>

​
Step 3: Create Your First File

1

Open File Explorer

In the center panel, you’ll see your project’s file tree. Right-click in the explorer to see options.
2

Create a New File

Right-click and select “New File” or click the + icon. Name your file with an extension (e.g., app.js, index.html, README.md).
Polaris supports syntax highlighting for:
  • JavaScript/TypeScript (.js, .ts, .jsx, .tsx)
  • HTML (.html)
  • CSS (.css)
  • JSON (.json)
  • Markdown (.md)
  • Python (.py)
3

Start Typing

Click on your new file to open it in the editor. The CodeMirror 6 editor provides:
  • Line numbers and code folding
  • Bracket matching
  • Indentation guides
  • Minimap overview
  • Auto-save (files save automatically as you type)

​
Step 4: Use AI Suggestions

Polaris provides real-time code completions as you type.
1

Start Coding

Begin typing in your file. After a brief pause (300ms debounce), Polaris analyzes your code:
// The suggestion system sends context to the AI
const payload = {
  fileName: 'app.js',
  code: fullFileContent,
  currentLine: 'function handleClick',
  previousLines: '...5 lines of context...',
  textBeforeCursor: 'function handle',
  textAfterCursor: 'Click() {',
  nextLines: '...5 lines of context...',
  lineNumber: 42
}
2

Review Suggestions

You’ll see ghost text (grayed out) suggesting your next code. This appears inline at your cursor position.
// Suggestions render as decorations
class SuggestionWidget extends WidgetType {
  toDOM() {
    const span = document.createElement("span");
    span.textContent = this.text;
    span.style.opacity = "0.4"; // Ghost text
    return span;
  }
}
3

Accept Suggestions

Press Tab to accept the suggestion. The ghost text becomes real code and your cursor moves to the end.
If you don’t want the suggestion, just keep typing - it will disappear and a new one will generate based on your changes.

​
Step 5: Use Quick Edit (Cmd+K)

Quick Edit lets you modify code using natural language instructions.
1

Select Code

Highlight the code you want to modify. A tooltip will appear with two options:
  • Add to Chat: Adds the selection to your conversation
  • Quick Edit (⌘K): Opens the inline edit interface
// Selection tooltip component
const quickEditButton = document.createElement("button");
quickEditButton.textContent = "Quick Edit";
quickEditButton.className = "p-1 px-2 hover:bg-foreground/10";
2

Describe the Change

Press Cmd+K (Mac) or Ctrl+K (Windows/Linux). Type your instruction:
  • “Add error handling”
  • “Convert this to async/await”
  • “Add TypeScript types”
  • “Refactor using modern ES6 syntax”
You can even include URLs to documentation:
// Polaris will scrape and use the docs
"Add validation using https://zod.dev"
3

Review and Apply

Polaris sends your selection and instruction to Claude Sonnet 4:
const prompt = `You are a code editing assistant.

<selected_code>
${selectedCode}
</selected_code>

<instruction>
${instruction}
</instruction>

Return ONLY the edited version of the selected code.
Maintain the same indentation level as the original.`;
The edited code replaces your selection automatically. If you don’t like it, use Cmd+Z to undo.

​
Step 6: Chat with AI Assistant

The conversation sidebar provides a ChatGPT-like interface with full project awareness.
1

Open Conversation Panel

The left sidebar shows your conversation history. Each project has its own conversation thread stored in Convex:
conversations: defineTable({
  projectId: v.id("projects"),
  title: v.string(),
  updatedAt: v.number(),
}).index("by_project", ["projectId"])
2

Ask Questions

Type questions or requests in the input at the bottom:
  • “Explain how this function works”
  • “Add a README with installation instructions”
  • “Find bugs in my authentication logic”
  • “Suggest improvements to this component”
3

Get Contextual Responses

The AI has access to your entire project structure and can reference specific files. Responses stream in real-time using the Vercel AI SDK.
In Part 1, the AI cannot directly modify files - this feature is coming in Part 2 with the AI Agent implementation using Inngest AgentKit.

​
Next Steps

You’re now ready to build with Polaris! Here are some things to try:

Organize Files

Create folders, rename files, and structure your project

Explore Keyboard Shortcuts

Use Cmd+K for quick edit and Tab for suggestions

Try Different Languages

Create Python, TypeScript, or Markdown files

Use Documentation URLs

Include URLs in Quick Edit to teach AI about libraries

​
Tips for Success

Make suggestions more accurate: Type at least 2-3 lines before expecting suggestions. The AI needs context to understand your intent.
Write better prompts: Be specific in your Quick Edit instructions. Instead of “improve this”, try “add input validation and error handling”.
Leverage conversation memory: The AI remembers your full conversation. Reference previous messages with “like you suggested before”.

​
Troubleshooting

  • Wait 300ms after typing for the debounce delay
  • Ensure you have at least 2-3 lines of code for context
  • Check that your cursor is at the end of a line
  • Make sure you’ve selected code first
  • Try clicking the “Quick Edit” button in the tooltip instead
  • Check browser console for errors (F12)
  • Files auto-save after 500ms of inactivity
  • Check your network connection
  • Look for the save indicator in the tab
  • Claude Sonnet 4 can take 2-5 seconds for complex requests
  • Try shorter, more focused prompts
  • Consider using Gemini 2.0 Flash for faster responses (see Installation)

​
Ready to Self-Host?

If you want to run Polaris on your own infrastructure with custom AI models and unlimited projects, check out the Installation Guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us