Get Started

Introduction

Castor is an IDE that can transform your natural language requirements into production-ready code. No need to arrive with a polished specification document, just describe what you're building to our AI agent, refine the requirements together, and watch your ideas take shape as code.

At the heart of Castor is bidirectional synchronization, also known as round-trip engineering. Any changes you make to your diagrams are automatically reflected in the code, and vice versa, keeping your documentation and code perfectly aligned throughout development.

Installation

Download Castor

Getting started is easy:

  1. Go to the Download page to install the IDE
  2. Open the downloaded file and follow the installation instructions for your operating system (Windows, MacOS, Linux)
  3. Open Castor and start coding!

Your First Project

This guide will walk you through Castor's primary features by working with a real project. You'll learn how to use the DAM agent, the diagram editor, the code generation and the code synchronization features to enhance your development workflow. To find this guide, visit the tutorial section.

Core Concepts

Understanding these core concepts will help you get the most out of Castor IDE.

Round-Trip Engineering

Round-trip engineering ensures that changes made in one artifact automatically propagate to related artifacts. In Castor:

  • Code → Diagram: Add a method in TypeScript, and it appears in the class diagram
  • Diagram → Code: Draw a new class in the diagram, and the TypeScript file is generated

DAM Agent

The DAM Agent is Castor's primary AI assistant. It orchestrates your entire development workflow from requirements to implementation.

What the DAM Agent Can Do

  • Gather Requirements: Transform natural language requirements into a structured document
  • Create Design Documents: Generate architectural documentation with design decisions, like non-functional requirements
  • Generate Diagrams: Create class diagrams and domain models from your requirements
  • Answer Questions: Help you understand your codebase and suggest improvements

AI Chat Interface

The AI Chat is your primary interface for interacting with Castor's agents.

Opening the Chat

Access the AI Chat via View → AI Chat. The chat panel opens on the right side of the IDE.

Chat Interface Components

  1. Text Input Box: Where you type your prompts and requests
  2. Attach Elements to Context: Add files or code snippets to provide context for your request
  3. Agent Selector (@): Use the @ symbol to select which AI agent to interact with (e.g., @DAM)
  4. Chat/Act Toggle: Controls whether the AI suggests changes for your approval or acts directly
  5. New Chat Session: Start a fresh conversation with the agent
  6. Show Chat History: View your previous conversation sessions
  7. Summarize Current Session: Get a summary of the current conversation
  8. Turn Auto Scrolling Off: Disable automatic scrolling to the latest message
  9. More Actions: Open the agent settings, AI history, AI settings
AI Chat Interface with numbered components

Chat vs Act Mode

The Chat/Act toggle gives you control over how the AI responds:

Chat Mode

The AI suggests changes and explains what it would do and acts. You can review and approve before any modifications are made. Best for understanding and learning.

Act Mode

The AI directly makes changes to your project files based on your prompt. Best when you're confident in your request and want faster results.

Agent Settings

Castor allows you to configure AI agents with your own API keys and choose different LLM providers for each agent. This gives you flexibility in how you interact with AI capabilities.

Accessing Agent Settings

To configure agent settings:

  1. Open the AI Chat panel via View → AI Chat
  2. Click the More Actions button (three dots) in the chat header
  3. Select Open Agent Settings

Adding Personal API Keys

You can use your own API keys from supported LLM providers to power the AI agents:

  1. Open the AI Settings panel, as shown in the gif below
  2. Select the model whose API key you want to configure (ex: OpenAI, Anthropic, Google)
  3. In the API Key field, enter your personal API key from your chosen provider
Adding an API key in the AI Settings panel

Supported Providers: OpenAI, Anthropic, Google (Gemini)

Switching LLMs Per Agent

Each agent can be configured to use a different LLM model:

  1. Open the Agent Settings panel
  2. Select the agent you want to configure
  3. Use the Language Model dropdown to select your preferred provider or select the default model
  4. The default model will be used if no specific model is selected and is listed below the dropdown

Castor Panel

The Castor Panel is your central hub for managing all project artifacts. It provides a tree view of your requirements, design documents, and diagrams.

Accessing the Castor Panel

  • Look for the Castor Beaver icon in the Activity Bar (left sidebar)
  • Click the icon to open the Castor Panel
  • The panel displays a tree structure of your project artifacts

Panel Sections

  • Requirements: Your requirements.md file containing user stories, functional requirements, and acceptance criteria
  • Design: The design.md file with architectural decisions, technical specifications, and non-functional requirements
  • Diagrams: Class diagrams and domain diagrams that visualize your project structure. Click a file to open it in the Diagram Editor

File Icon Colors: An orange icon indicates the file has been created, while a grey icon means the file hasn't been generated yet.

Context Menu Actions

Right-click on items in the Castor Panel for additional options:

  • Delete File: Remove a file from your project
  • Open in Editor: View the file in the appropriate editor

Requirements Management

Castor helps you capture, organize, and track requirements throughout your development process.

Creating Requirements

Using the DAM Agent:

  1. Open AI Chat and select @DAM
  2. Describe your project requirements in natural language
  3. The agent creates a structured requirements.md file
  4. Requirements are stored with user stories, acceptance criteria, and priorities

Extracting from Code Comments:

  1. Select text in your editor that describes a requirement
  2. Right-click and choose "Extract Requirement Symbol"
  3. Classify the requirement type (functional, non-functional, user story)
  4. The requirement is added to your requirements store and linked to the IR

Diagram Editor

Castor includes a powerful visual diagram editor powered by GLSP (Graphical Language Server Protocol). It supports UML-style class diagrams and domain entity diagrams.

Opening Diagrams

  • Click on a diagram file in the Castor Panel
  • The diagram opens in the visual editor with the canvas in the center
  • The Palette appears on the right side with available elements

Diagram Elements

The following elements are available:

Node Types:

  • Class: Represents a TypeScript/NestJS class with properties and methods
  • Interface: Represents a TypeScript interface
  • Package: Groups related classes and interfaces
  • Enum: Represents enumeration types

Edge Types (Relationships):

  • Association: Basic relationship between classes
  • Aggregation: "Has-a" relationship (hollow diamond)
  • Composition: Strong "owns" relationship (filled diamond)
  • Inheritance: "Is-a" relationship (extends)

Editing Diagrams

  1. Add Elements: Select an element from the Palette, then click on the canvas to create it
  2. Select Elements: Click on any element to select it
  3. Move Elements: Drag selected elements to reposition them
  4. Edit Labels: Double-click on an element to rename it
  5. Add Methods/Attributes: Right-click on an element and use the context menu to add methods or attributes
  6. Create Connections: Use the Connection Tool from the palette, then click and drag from one element to another
  7. Delete Entities: Select "Enable deletion tool" in the diagram Palette, then click on the entity you want to delete
  8. Delete Attributes/Methods: Right-click on the attribute or method you want to delete and choose "Delete"

Diagram Synchronization

Diagrams are synchronized with your code when you save and click the Sync button:

  • Adding a class in the diagram creates a corresponding TypeScript file
  • Adding a method to a code file updates the class in the diagram
  • Creating relationships in the diagram generates imports and references in code

Save your diagram with Ctrl+S /Cmd+S to trigger synchronization.

Synchronization

Castor keeps your code, diagrams, and requirements in sync automatically. This is the core of round-trip engineering - changes in one artifact propagate to related artifacts.

How Synchronization Works

  1. Change Detection: When you save a file, Castor detects what changed
  2. Event Queuing: The change is added to the sync queue with a source identifier
  3. IR Update: The Intermediate Representation is updated to reflect the change
  4. Propagation: Sync handlers propagate the change to other artifacts
  5. Loop Prevention: The source identifier prevents infinite update loops

Sync Handlers

Three specialized handlers process synchronization events:

  • Code Sync Handler: Propagates changes to TypeScript files
  • Diagram Sync Handler: Updates GLSP diagram models
  • Requirements Sync Handler: Updates requirements documents

Triggering Synchronization

Automatic Sync:

  • Sync triggers automatically when you save files (Ctrl+S / Cmd+S)
  • The status bar shows "Syncing..." during synchronization
  • Once complete, it displays "Synced" with success/failure counts

Manual Sync:

  • Press Ctrl+Shift+P / Cmd+Shift+P to open the Command Palette
  • Type "Castor: Synchronize Code and Diagrams"
  • Or access via Go → Sync with Diagrams

Auto-Save Warning:

If auto-save is enabled in your editor settings, Castor will warn you. Auto-save can cause frequent synchronization events. For best results, disable auto-save and manually save when ready.

Code Generation

Castor generates TypeScript code from your IR and diagram structures. It uses ts-morph for AST manipulation to produce clean, properly formatted code.

Supported Frameworks

Code generation is currently optimized for NestJS backend development:

  • Services: Business logic layer with dependency injection
  • Controllers: REST API endpoints with decorators
  • Modules: NestJS module definitions with imports/exports
  • DTOs: Data Transfer Objects for request/response validation
  • Entities: Database entity definitions (TypeORM compatible)
  • Repositories: Data access layer components

How Code Generation Works

  1. IR Analysis: The codegen service reads your IR graph
  2. Symbol Conversion: IR nodes are converted to code symbols
  3. Framework Conversion: Symbols are converted to framework-specific code (NestJS)
  4. File Writing: Generated code is written to the src folder

Code Analysis Features

Castor can also analyze existing TypeScript code to extract:

  • Classes with properties, methods, constructors, and decorators
  • Interfaces with methods and type parameters
  • Enums with members and values
  • Access modifiers (public, private, protected)
  • Import/export relationships

File Monitoring

Castor watches your project files for changes and triggers synchronization automatically.

Monitored Files

The file monitor tracks:

  • TypeScript files (.ts)
  • File creations, updates, and deletions

The monitor excludes:

  • Test files (*.spec.ts, *.test.ts)
  • Node modules (node_modules/)
  • Build outputs (dist/, lib/)

Status Bar Indicator

Look at the status bar at the bottom right of the IDE:

  • Syncing...: Synchronization is in progress
  • Synced: All changes synchronized successfully
  • Stats: Shows success/failure/skipped counts

Commands & Keyboard Shortcuts

Quick reference for Castor-specific commands and keyboard shortcuts.

Command Palette Commands

Access via Ctrl+Shift+P / Cmd+Shift+P:

CommandDescription
Castor: Synchronize Code and DiagramsManually trigger synchronization between code and diagrams
Castor: Test ts-morph IntegrationTest code analysis on the currently open file
Extract Requirement SymbolCreate a requirement from selected text

Menu Locations

ActionMenu Path
Open AI ChatView → AI Chat
Sync with DiagramsGo → Sync with Diagrams
Ask DAM Agent (in editor)Right-click → Ask DAM Agent
Extract RequirementRight-click → Extract Requirement Symbol

Keyboard Shortcuts

ActionWindows/LinuxmacOS
Save File (triggers sync)Ctrl+SCmd+S
Command PaletteCtrl+Shift+PCmd+Shift+P

Configuration

Castor provides several configuration options to customize your experience.

AI Preferences

Access via File → Preferences → Settings and search for "castor":

  • Subscription Tier: Displays your current subscription tier (Free or Premium)
  • Enable Analytics: Opt-in for anonymous usage analytics

Language Support

Castor supports all programming languages for creating requirements, design documents, and diagrams.

However, Round-Trip Engineering features (code generation and synchronization) are currently only available for NestJS. We are currently working on adding support for more languages and frameworks in future releases.

Page updated: January 2025

Next: Tutorial →